@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11
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
|
@@ -1,205 +0,0 @@
|
|
|
1
|
-
# New Service - Test Generation
|
|
2
|
-
|
|
3
|
-
> **Purpose**: Create unit tests for the new service.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Test File Location
|
|
8
|
-
|
|
9
|
-
Create: `test/unit/spec/services/ServiceName.ts`
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Test File Template
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
import 'jsdom-global/register';
|
|
17
|
-
import MockWebex from '@webex/test-helper-mock-webex';
|
|
18
|
-
import ServiceName, {
|
|
19
|
-
ServiceListResponse,
|
|
20
|
-
ServiceSearchParams,
|
|
21
|
-
} from '../../../../src/services/ServiceName';
|
|
22
|
-
|
|
23
|
-
jest.mock('../../../../src/logger-proxy', () => ({
|
|
24
|
-
__esModule: true,
|
|
25
|
-
default: {
|
|
26
|
-
log: jest.fn(),
|
|
27
|
-
error: jest.fn(),
|
|
28
|
-
info: jest.fn(),
|
|
29
|
-
warn: jest.fn(),
|
|
30
|
-
trace: jest.fn(),
|
|
31
|
-
initialize: jest.fn(),
|
|
32
|
-
},
|
|
33
|
-
}));
|
|
34
|
-
|
|
35
|
-
describe('ServiceName', () => {
|
|
36
|
-
let webex: any;
|
|
37
|
-
let service: ServiceName;
|
|
38
|
-
|
|
39
|
-
// Mock data
|
|
40
|
-
const mockOrgId = 'mock-org-id';
|
|
41
|
-
const mockResponse: ServiceListResponse = {
|
|
42
|
-
data: [
|
|
43
|
-
{ id: 'item-1', name: 'Item 1' },
|
|
44
|
-
{ id: 'item-2', name: 'Item 2' },
|
|
45
|
-
],
|
|
46
|
-
meta: {
|
|
47
|
-
page: 0,
|
|
48
|
-
pageSize: 50,
|
|
49
|
-
totalPages: 1,
|
|
50
|
-
totalRecords: 2,
|
|
51
|
-
},
|
|
52
|
-
};
|
|
53
|
-
|
|
54
|
-
beforeEach(() => {
|
|
55
|
-
webex = MockWebex({
|
|
56
|
-
logger: {
|
|
57
|
-
log: jest.fn(),
|
|
58
|
-
error: jest.fn(),
|
|
59
|
-
info: jest.fn(),
|
|
60
|
-
},
|
|
61
|
-
credentials: {
|
|
62
|
-
getOrgId: jest.fn(() => mockOrgId),
|
|
63
|
-
},
|
|
64
|
-
request: jest.fn(),
|
|
65
|
-
});
|
|
66
|
-
|
|
67
|
-
service = new ServiceName(webex);
|
|
68
|
-
});
|
|
69
|
-
|
|
70
|
-
afterEach(() => {
|
|
71
|
-
jest.clearAllMocks();
|
|
72
|
-
});
|
|
73
|
-
|
|
74
|
-
describe('getItems', () => {
|
|
75
|
-
it('should fetch items successfully', async () => {
|
|
76
|
-
// Arrange
|
|
77
|
-
webex.request.mockResolvedValue({ body: mockResponse });
|
|
78
|
-
|
|
79
|
-
// Act
|
|
80
|
-
const result = await service.getItems();
|
|
81
|
-
|
|
82
|
-
// Assert
|
|
83
|
-
expect(result).toEqual(mockResponse);
|
|
84
|
-
expect(webex.request).toHaveBeenCalledWith({
|
|
85
|
-
method: 'GET',
|
|
86
|
-
uri: expect.stringContaining(mockOrgId),
|
|
87
|
-
});
|
|
88
|
-
});
|
|
89
|
-
|
|
90
|
-
it('should apply pagination parameters', async () => {
|
|
91
|
-
// Arrange
|
|
92
|
-
webex.request.mockResolvedValue({ body: mockResponse });
|
|
93
|
-
const params: ServiceSearchParams = { page: 1, pageSize: 25 };
|
|
94
|
-
|
|
95
|
-
// Act
|
|
96
|
-
await service.getItems(params);
|
|
97
|
-
|
|
98
|
-
// Assert
|
|
99
|
-
expect(webex.request).toHaveBeenCalledWith({
|
|
100
|
-
method: 'GET',
|
|
101
|
-
uri: expect.stringContaining('page=1'),
|
|
102
|
-
});
|
|
103
|
-
expect(webex.request).toHaveBeenCalledWith({
|
|
104
|
-
method: 'GET',
|
|
105
|
-
uri: expect.stringContaining('pageSize=25'),
|
|
106
|
-
});
|
|
107
|
-
});
|
|
108
|
-
|
|
109
|
-
it('should apply search parameter', async () => {
|
|
110
|
-
// Arrange
|
|
111
|
-
webex.request.mockResolvedValue({ body: mockResponse });
|
|
112
|
-
const params: ServiceSearchParams = { search: 'test' };
|
|
113
|
-
|
|
114
|
-
// Act
|
|
115
|
-
await service.getItems(params);
|
|
116
|
-
|
|
117
|
-
// Assert
|
|
118
|
-
expect(webex.request).toHaveBeenCalledWith({
|
|
119
|
-
method: 'GET',
|
|
120
|
-
uri: expect.stringContaining('search=test'),
|
|
121
|
-
});
|
|
122
|
-
});
|
|
123
|
-
|
|
124
|
-
it('should throw error on API failure', async () => {
|
|
125
|
-
// Arrange
|
|
126
|
-
const mockError = new Error('API Error');
|
|
127
|
-
webex.request.mockRejectedValue(mockError);
|
|
128
|
-
|
|
129
|
-
// Act & Assert
|
|
130
|
-
await expect(service.getItems()).rejects.toThrow('API Error');
|
|
131
|
-
});
|
|
132
|
-
});
|
|
133
|
-
|
|
134
|
-
describe('getItemById', () => {
|
|
135
|
-
it('should fetch single item successfully', async () => {
|
|
136
|
-
// Arrange
|
|
137
|
-
const mockItem = { id: 'item-1', name: 'Item 1' };
|
|
138
|
-
webex.request.mockResolvedValue({ body: mockItem });
|
|
139
|
-
|
|
140
|
-
// Act
|
|
141
|
-
const result = await service.getItemById('item-1');
|
|
142
|
-
|
|
143
|
-
// Assert
|
|
144
|
-
expect(result).toEqual(mockItem);
|
|
145
|
-
expect(webex.request).toHaveBeenCalledWith({
|
|
146
|
-
method: 'GET',
|
|
147
|
-
uri: expect.stringContaining('item-1'),
|
|
148
|
-
});
|
|
149
|
-
});
|
|
150
|
-
|
|
151
|
-
it('should throw error if item not found', async () => {
|
|
152
|
-
// Arrange
|
|
153
|
-
const mockError = new Error('Not Found');
|
|
154
|
-
webex.request.mockRejectedValue(mockError);
|
|
155
|
-
|
|
156
|
-
// Act & Assert
|
|
157
|
-
await expect(service.getItemById('invalid-id')).rejects.toThrow('Not Found');
|
|
158
|
-
});
|
|
159
|
-
});
|
|
160
|
-
});
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
---
|
|
164
|
-
|
|
165
|
-
## Test Integration with cc.ts
|
|
166
|
-
|
|
167
|
-
Add to `test/unit/spec/cc.ts`:
|
|
168
|
-
|
|
169
|
-
```typescript
|
|
170
|
-
describe('cc.serviceName', () => {
|
|
171
|
-
it('should initialize service on ready', () => {
|
|
172
|
-
expect(webex.cc.serviceName).toBeDefined();
|
|
173
|
-
});
|
|
174
|
-
|
|
175
|
-
it('should fetch items through service', async () => {
|
|
176
|
-
// Mock the service method
|
|
177
|
-
const mockResponse = { data: [], meta: {} };
|
|
178
|
-
jest.spyOn(webex.cc.serviceName, 'getItems').mockResolvedValue(mockResponse);
|
|
179
|
-
|
|
180
|
-
// Act
|
|
181
|
-
const result = await webex.cc.serviceName.getItems();
|
|
182
|
-
|
|
183
|
-
// Assert
|
|
184
|
-
expect(result).toEqual(mockResponse);
|
|
185
|
-
});
|
|
186
|
-
});
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## Running Tests
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
# Run specific test file
|
|
195
|
-
yarn workspace @webex/contact-center test -- --testPathPattern=ServiceName
|
|
196
|
-
|
|
197
|
-
# Run with coverage
|
|
198
|
-
yarn workspace @webex/contact-center test -- --coverage --testPathPattern=ServiceName
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
---
|
|
202
|
-
|
|
203
|
-
## Next Step
|
|
204
|
-
|
|
205
|
-
Proceed to: [`05-validation.md`](05-validation.md)
|
|
@@ -1,145 +0,0 @@
|
|
|
1
|
-
# New Service - Validation Checklist
|
|
2
|
-
|
|
3
|
-
> **Purpose**: Final quality check before completing service creation.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Code Quality Checklist
|
|
8
|
-
|
|
9
|
-
### Service Class
|
|
10
|
-
- [ ] File created at correct location (based on placement from pre-questions Q3)
|
|
11
|
-
- [ ] Class has proper JSDoc with `@public` tag
|
|
12
|
-
- [ ] Methods have JSDoc with `@param`, `@returns`, `@example`
|
|
13
|
-
- [ ] Uses `LoggerProxy` for all logging (no `console.log`)
|
|
14
|
-
- [ ] Error handling uses `getErrorDetails` pattern (logs and re-throws)
|
|
15
|
-
- [ ] Module name constant defined (`SERVICE_FILE`)
|
|
16
|
-
- [ ] Method name constants defined (`METHODS`)
|
|
17
|
-
|
|
18
|
-
### Types & Constants
|
|
19
|
-
- [ ] Types placed in the correct location:
|
|
20
|
-
- Folder-based service: service folder's `types.ts`
|
|
21
|
-
- Single-file service: root `src/types.ts`
|
|
22
|
-
- Sub-module: parent service's `types.ts`
|
|
23
|
-
- [ ] Constants: no duplicates — every constant was searched across the hierarchy before adding:
|
|
24
|
-
- `src/constants.ts` (SDK-wide: file names, method names, global settings)
|
|
25
|
-
- `src/services/constants.ts` (shared: API gateways, auth, network)
|
|
26
|
-
- `src/metrics/constants.ts` (all metric event names)
|
|
27
|
-
- `src/services/config/constants.ts` (endpoint maps, pagination, agent states)
|
|
28
|
-
- `src/services/{ServiceName}/constants.ts` (service-specific only)
|
|
29
|
-
- [ ] Constants placed at the correct level (not duplicated at a lower level when shared exists)
|
|
30
|
-
- [ ] New `constants.ts` file created ONLY if service is folder-based AND no existing file AND constants are service-specific
|
|
31
|
-
- [ ] All public types have JSDoc
|
|
32
|
-
- [ ] Response types match actual API response
|
|
33
|
-
- [ ] Parameter types define all optional/required fields
|
|
34
|
-
|
|
35
|
-
### Metrics
|
|
36
|
-
- [ ] `metricsManager.timeEvent` called at method entry with success + failure event names
|
|
37
|
-
- [ ] `metricsManager.trackEvent` called on success path
|
|
38
|
-
- [ ] `metricsManager.trackEvent` called on failure path (in catch block)
|
|
39
|
-
- [ ] Metric event names added to `src/metrics/constants.ts` (`METRIC_EVENT_NAMES`)
|
|
40
|
-
|
|
41
|
-
### Integration
|
|
42
|
-
- [ ] Service initialized at the correct integration point:
|
|
43
|
-
- Folder-based / single-file: in `cc.ts` or `Services` singleton (depends on AQM vs non-AQM)
|
|
44
|
-
- Sub-module: instantiated by parent service
|
|
45
|
-
- [ ] Types re-exported from `src/types.ts` (if public)
|
|
46
|
-
|
|
47
|
-
### Tests
|
|
48
|
-
- [ ] Test file created mirroring source path under `test/unit/spec/`
|
|
49
|
-
- [ ] LoggerProxy mocked
|
|
50
|
-
- [ ] Success cases tested
|
|
51
|
-
- [ ] Error cases tested
|
|
52
|
-
- [ ] Metrics tracking verified (timeEvent and trackEvent calls asserted)
|
|
53
|
-
- [ ] Tests pass: `yarn workspace @webex/contact-center test:unit`
|
|
54
|
-
|
|
55
|
-
---
|
|
56
|
-
|
|
57
|
-
## Pattern Compliance
|
|
58
|
-
|
|
59
|
-
### LoggerProxy Usage
|
|
60
|
-
```typescript
|
|
61
|
-
// ✅ Correct
|
|
62
|
-
LoggerProxy.info('Starting operation', {
|
|
63
|
-
module: SERVICE_FILE,
|
|
64
|
-
method: METHODS.GET_ITEMS,
|
|
65
|
-
});
|
|
66
|
-
|
|
67
|
-
// ❌ Wrong
|
|
68
|
-
console.log('Starting operation');
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
### Error Handling
|
|
72
|
-
```typescript
|
|
73
|
-
// ✅ Correct
|
|
74
|
-
catch (error) {
|
|
75
|
-
LoggerProxy.error(`Failed: ${error}`, {
|
|
76
|
-
module: SERVICE_FILE,
|
|
77
|
-
method: METHODS.GET_ITEMS,
|
|
78
|
-
error,
|
|
79
|
-
});
|
|
80
|
-
throw error;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
// ❌ Wrong - swallowing error
|
|
84
|
-
catch (error) {
|
|
85
|
-
console.error(error);
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### Type Exports
|
|
90
|
-
```typescript
|
|
91
|
-
// ✅ Correct - in src/types.ts
|
|
92
|
-
export type {
|
|
93
|
-
ServiceItem,
|
|
94
|
-
ServiceSearchParams,
|
|
95
|
-
ServiceListResponse,
|
|
96
|
-
} from './services/ServiceName';
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## Build & Test Verification
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
# Lint
|
|
105
|
-
yarn workspace @webex/contact-center test:style
|
|
106
|
-
|
|
107
|
-
# Test unit tests
|
|
108
|
-
yarn workspace @webex/contact-center test:unit
|
|
109
|
-
|
|
110
|
-
# Build
|
|
111
|
-
yarn workspace @webex/contact-center build:src
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
All should pass without errors.
|
|
115
|
-
|
|
116
|
-
---
|
|
117
|
-
|
|
118
|
-
## Documentation
|
|
119
|
-
|
|
120
|
-
### Update Root AGENTS.md?
|
|
121
|
-
If this is a significant new service, update the root [`AGENTS.md`](../../../AGENTS.md):
|
|
122
|
-
- [ ] Added new service to the [Service Routing Table](../../../AGENTS.md#service-routing-table)
|
|
123
|
-
- [ ] Added to repository structure tree
|
|
124
|
-
- [ ] Added usage example if applicable
|
|
125
|
-
|
|
126
|
-
### Create Service ai-docs?
|
|
127
|
-
For complex services, create service-level documentation (use [`create-agents-md.md`](../documentation/create-agents-md.md) and [`create-architecture-md.md`](../documentation/create-architecture-md.md) templates):
|
|
128
|
-
- [ ] `src/services/ServiceName/ai-docs/AGENTS.md` — usage guide, API reference
|
|
129
|
-
- [ ] `src/services/ServiceName/ai-docs/ARCHITECTURE.md` — technical deep-dive, data flow
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## Final Review
|
|
134
|
-
|
|
135
|
-
Ask yourself:
|
|
136
|
-
1. Can another developer understand this service by reading the JSDoc?
|
|
137
|
-
2. Are all error paths properly handled and logged?
|
|
138
|
-
3. Do tests cover the main use cases?
|
|
139
|
-
4. Is the API surface clean and consistent with other services?
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## Complete!
|
|
144
|
-
|
|
145
|
-
Service creation is complete when all checkboxes are checked.
|
|
@@ -1,350 +0,0 @@
|
|
|
1
|
-
# Metrics Module - AI Agent Guide
|
|
2
|
-
|
|
3
|
-
> **Legacy/reference-only.** Canonical SDD: [`metrics-spec.md`](metrics-spec.md). Use the package [manifest](../../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
|
|
4
|
-
|
|
5
|
-
> **Purpose**: Track behavioral, operational, and business metrics for Contact Center SDK operations using a singleton `MetricsManager`. Provides event timing, payload preparation, batching, and submission to the Webex metrics backend.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Quick Start
|
|
10
|
-
|
|
11
|
-
```typescript
|
|
12
|
-
import MetricsManager from '../metrics/MetricsManager';
|
|
13
|
-
import {METRIC_EVENT_NAMES} from '../metrics/constants';
|
|
14
|
-
|
|
15
|
-
// Get the singleton instance (webex is set during cc.register())
|
|
16
|
-
const metrics = MetricsManager.getInstance();
|
|
17
|
-
|
|
18
|
-
// Time an operation, then track its result
|
|
19
|
-
metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
|
|
20
|
-
// ... perform the operation ...
|
|
21
|
-
metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
## Key Capabilities
|
|
27
|
-
|
|
28
|
-
- **Singleton Pattern**: Single `MetricsManager` instance shared across the entire SDK
|
|
29
|
-
- **Three Metric Types**: Behavioral (user actions), operational (system events), business (business-level analytics)
|
|
30
|
-
- **Event Timing**: `timeEvent` + `trackEvent` pattern automatically calculates `duration_ms`
|
|
31
|
-
- **Queued Submission**: Events are queued until the Webex SDK is ready, then submitted in order
|
|
32
|
-
- **Behavioral Taxonomy**: Structured `product.agent.target.verb` naming convention for behavioral events
|
|
33
|
-
- **Payload Preparation**: Automatic cleanup of empty fields, space-to-underscore conversion, and `tabHidden` metadata
|
|
34
|
-
- **AQM Response Helpers**: Static methods to extract common tracking fields from AQM responses
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## API Reference
|
|
39
|
-
|
|
40
|
-
### Methods
|
|
41
|
-
|
|
42
|
-
#### `MetricsManager.getInstance(options?)`
|
|
43
|
-
|
|
44
|
-
Returns the singleton instance. On first call with `{webex}`, binds to the Webex SDK and begins listening for the `ready` event.
|
|
45
|
-
|
|
46
|
-
**Parameters**:
|
|
47
|
-
- `options` (object, optional): `{webex: WebexSDK}` - The Webex SDK instance
|
|
48
|
-
|
|
49
|
-
**Returns**: `MetricsManager`
|
|
50
|
-
|
|
51
|
-
**Example**:
|
|
52
|
-
```typescript
|
|
53
|
-
// During initialization (called internally by cc.register())
|
|
54
|
-
const metrics = MetricsManager.getInstance({webex});
|
|
55
|
-
|
|
56
|
-
// Subsequent calls (no webex needed)
|
|
57
|
-
const metrics = MetricsManager.getInstance();
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
#### `metrics.timeEvent(keys)`
|
|
63
|
-
|
|
64
|
-
Starts a timer for one or more event keys. When a matching `trackEvent` / `trackBehavioralEvent` / `trackOperationalEvent` / `trackBusinessEvent` is called, `duration_ms` is automatically added to the payload.
|
|
65
|
-
|
|
66
|
-
**Parameters**:
|
|
67
|
-
- `keys` (string | string[]): One or more `METRIC_EVENT_NAMES` values. The first key is the tracking key; all keys in the array will resolve the same timer.
|
|
68
|
-
|
|
69
|
-
**Returns**: `void`
|
|
70
|
-
|
|
71
|
-
**Example**:
|
|
72
|
-
```typescript
|
|
73
|
-
// Single key
|
|
74
|
-
metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
|
|
75
|
-
|
|
76
|
-
// Multiple keys (success/failure share one timer)
|
|
77
|
-
metrics.timeEvent([
|
|
78
|
-
METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
|
|
79
|
-
METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
|
|
80
|
-
]);
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
---
|
|
84
|
-
|
|
85
|
-
#### `metrics.trackEvent(name, payload?, metricServices?)`
|
|
86
|
-
|
|
87
|
-
Tracks an event across one or more metric services.
|
|
88
|
-
|
|
89
|
-
**Parameters**:
|
|
90
|
-
- `name` (METRIC_EVENT_NAMES): The event name constant
|
|
91
|
-
- `payload` (EventPayload, optional): Key-value pairs of event data
|
|
92
|
-
- `metricServices` (MetricsType[], optional): Array of `'behavioral'` | `'operational'` | `'business'` (default: `['behavioral']`)
|
|
93
|
-
|
|
94
|
-
**Returns**: `void`
|
|
95
|
-
|
|
96
|
-
**Example**:
|
|
97
|
-
```typescript
|
|
98
|
-
// Behavioral only (default)
|
|
99
|
-
metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
|
|
100
|
-
|
|
101
|
-
// Multiple services
|
|
102
|
-
metrics.trackEvent(
|
|
103
|
-
METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
|
|
104
|
-
{interactionId: 'abc'},
|
|
105
|
-
['behavioral', 'operational']
|
|
106
|
-
);
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
---
|
|
110
|
-
|
|
111
|
-
#### `metrics.trackBehavioralEvent(name, options?)`
|
|
112
|
-
|
|
113
|
-
Tracks a single behavioral event. Looks up the event taxonomy from `behavioral-events.ts` and submits via `webex.internal.newMetrics.submitBehavioralEvent`.
|
|
114
|
-
|
|
115
|
-
**Parameters**:
|
|
116
|
-
- `name` (METRIC_EVENT_NAMES): The event name
|
|
117
|
-
- `options` (EventPayload, optional): Additional payload data
|
|
118
|
-
|
|
119
|
-
**Returns**: `void`
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
#### `metrics.trackOperationalEvent(name, options?)`
|
|
124
|
-
|
|
125
|
-
Tracks a single operational event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitOperationalEvent`.
|
|
126
|
-
|
|
127
|
-
**Parameters**:
|
|
128
|
-
- `name` (METRIC_EVENT_NAMES): The event name
|
|
129
|
-
- `options` (EventPayload, optional): Additional payload data
|
|
130
|
-
|
|
131
|
-
**Returns**: `void`
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
#### `metrics.trackBusinessEvent(name, options?)`
|
|
136
|
-
|
|
137
|
-
Tracks a single business event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitBusinessEvent` with `appType: 'wxcc_sdk'`.
|
|
138
|
-
|
|
139
|
-
**Parameters**:
|
|
140
|
-
- `name` (METRIC_EVENT_NAMES): The event name
|
|
141
|
-
- `options` (EventPayload, optional): Additional payload data
|
|
142
|
-
|
|
143
|
-
**Returns**: `void`
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
#### `metrics.setMetricsDisabled(disabled)`
|
|
148
|
-
|
|
149
|
-
Enables or disables metrics collection. When disabled, all pending events are cleared and new events are dropped.
|
|
150
|
-
|
|
151
|
-
**Parameters**:
|
|
152
|
-
- `disabled` (boolean): `true` to disable, `false` to enable
|
|
153
|
-
|
|
154
|
-
**Returns**: `void`
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
#### `MetricsManager.getCommonTrackingFieldForAQMResponse(response)`
|
|
159
|
-
|
|
160
|
-
Static helper that extracts common tracking fields from an AQM success response.
|
|
161
|
-
|
|
162
|
-
**Parameters**:
|
|
163
|
-
- `response` (any): The AQM response object
|
|
164
|
-
|
|
165
|
-
**Returns**: `Record<string, any>` with fields: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
|
|
166
|
-
|
|
167
|
-
**Example**:
|
|
168
|
-
```typescript
|
|
169
|
-
const fields = MetricsManager.getCommonTrackingFieldForAQMResponse(aqmResponse);
|
|
170
|
-
metrics.trackEvent(METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS, {
|
|
171
|
-
...fields,
|
|
172
|
-
interactionId: task.interactionId,
|
|
173
|
-
});
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
#### `MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failureResponse)`
|
|
179
|
-
|
|
180
|
-
Static helper that extracts common tracking fields from an AQM failure response.
|
|
181
|
-
|
|
182
|
-
**Parameters**:
|
|
183
|
-
- `failureResponse` (Failure): The AQM failure response object
|
|
184
|
-
|
|
185
|
-
**Returns**: `Record<string, any>` with fields: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
#### `MetricsManager.resetInstance()`
|
|
190
|
-
|
|
191
|
-
Resets the singleton instance. Used for testing only.
|
|
192
|
-
|
|
193
|
-
**Returns**: `void`
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## Metric Event Names
|
|
198
|
-
|
|
199
|
-
All event names are defined in `METRIC_EVENT_NAMES` (`constants.ts`). Events follow a `<Category> <Action> <Result>` pattern.
|
|
200
|
-
|
|
201
|
-
### Agent Events
|
|
202
|
-
|
|
203
|
-
| Constant | Value | Description |
|
|
204
|
-
|----------|-------|-------------|
|
|
205
|
-
| `STATION_LOGIN_SUCCESS` | `'Station Login Success'` | Agent station login succeeded |
|
|
206
|
-
| `STATION_LOGIN_FAILED` | `'Station Login Failed'` | Agent station login failed |
|
|
207
|
-
| `STATION_LOGOUT_SUCCESS` | `'Station Logout Success'` | Agent station logout succeeded |
|
|
208
|
-
| `STATION_LOGOUT_FAILED` | `'Station Logout Failed'` | Agent station logout failed |
|
|
209
|
-
| `STATION_RELOGIN_SUCCESS` | `'Station Relogin Success'` | Silent relogin succeeded |
|
|
210
|
-
| `STATION_RELOGIN_FAILED` | `'Station Relogin Failed'` | Silent relogin failed |
|
|
211
|
-
| `AGENT_STATE_CHANGE_SUCCESS` | `'Agent State Change Success'` | State change succeeded |
|
|
212
|
-
| `AGENT_STATE_CHANGE_FAILED` | `'Agent State Change Failed'` | State change failed |
|
|
213
|
-
| `FETCH_BUDDY_AGENTS_SUCCESS` | `'Fetch Buddy Agents Success'` | Buddy agents fetch succeeded |
|
|
214
|
-
| `FETCH_BUDDY_AGENTS_FAILED` | `'Fetch Buddy Agents Failed'` | Buddy agents fetch failed |
|
|
215
|
-
| `AGENT_RONA` | `'Agent RONA'` | Agent Ring-On-No-Answer triggered |
|
|
216
|
-
| `AGENT_CONTACT_ASSIGN_FAILED` | `'Agent Contact Assign Failed'` | Contact assignment failed |
|
|
217
|
-
| `AGENT_INVITE_FAILED` | `'Agent Invite Failed'` | Agent invite failed |
|
|
218
|
-
| `AGENT_DEVICE_TYPE_UPDATE_SUCCESS` | `'Agent Device Type Update Success'` | Device type update succeeded |
|
|
219
|
-
| `AGENT_DEVICE_TYPE_UPDATE_FAILED` | `'Agent Device Type Update Failed'` | Device type update failed |
|
|
220
|
-
|
|
221
|
-
### Task Events
|
|
222
|
-
|
|
223
|
-
| Constant | Value | Description |
|
|
224
|
-
|----------|-------|-------------|
|
|
225
|
-
| `TASK_ACCEPT_SUCCESS` / `FAILED` | `'Task Accept ...'` | Task accept result |
|
|
226
|
-
| `TASK_DECLINE_SUCCESS` / `FAILED` | `'Task Decline ...'` | Task decline result |
|
|
227
|
-
| `TASK_END_SUCCESS` / `FAILED` | `'Task End ...'` | Task end result |
|
|
228
|
-
| `TASK_WRAPUP_SUCCESS` / `FAILED` | `'Task Wrapup ...'` | Task wrapup result |
|
|
229
|
-
| `TASK_HOLD_SUCCESS` / `FAILED` | `'Task Hold ...'` | Task hold result |
|
|
230
|
-
| `TASK_RESUME_SUCCESS` / `FAILED` | `'Task Resume ...'` | Task resume result |
|
|
231
|
-
| `TASK_CONSULT_START_SUCCESS` / `FAILED` | `'Task Consult Start ...'` | Consult start result |
|
|
232
|
-
| `TASK_CONSULT_END_SUCCESS` / `FAILED` | `'Task Consult End ...'` | Consult end result |
|
|
233
|
-
| `TASK_TRANSFER_SUCCESS` / `FAILED` | `'Task Transfer ...'` | Transfer result |
|
|
234
|
-
| `TASK_PAUSE_RECORDING_SUCCESS` / `FAILED` | `'Task Pause Recording ...'` | Pause recording result |
|
|
235
|
-
| `TASK_RESUME_RECORDING_SUCCESS` / `FAILED` | `'Task Resume Recording ...'` | Resume recording result |
|
|
236
|
-
| `TASK_ACCEPT_CONSULT_SUCCESS` / `FAILED` | `'Task Accept Consult ...'` | Accept consult result |
|
|
237
|
-
| `TASK_AUTO_ANSWER_SUCCESS` / `FAILED` | `'Task Auto Answer ...'` | Auto-answer result |
|
|
238
|
-
| `TASK_OUTDIAL_SUCCESS` / `FAILED` | `'Task Outdial ...'` | Outdial result |
|
|
239
|
-
|
|
240
|
-
### Conference Events
|
|
241
|
-
|
|
242
|
-
| Constant | Value | Description |
|
|
243
|
-
|----------|-------|-------------|
|
|
244
|
-
| `TASK_CONFERENCE_START_SUCCESS` / `FAILED` | `'Task Conference Start ...'` | Conference start result |
|
|
245
|
-
| `TASK_CONFERENCE_END_SUCCESS` / `FAILED` | `'Task Conference End ...'` | Conference end result |
|
|
246
|
-
| `TASK_CONFERENCE_TRANSFER_SUCCESS` / `FAILED` | `'Task Conference Transfer ...'` | Conference transfer result |
|
|
247
|
-
| `TASK_CONFERENCE_EXIT_SUCCESS` / `FAILED` | `'Task Conference Exit ...'` | Conference exit result |
|
|
248
|
-
| `TASK_SWITCH_CALL_SUCCESS` / `FAILED` | `'Task Switch Call ...'` | Switch call result |
|
|
249
|
-
|
|
250
|
-
### System Events
|
|
251
|
-
|
|
252
|
-
| Constant | Value | Description |
|
|
253
|
-
|----------|-------|-------------|
|
|
254
|
-
| `WEBSOCKET_REGISTER_SUCCESS` / `FAILED` | `'Websocket Register ...'` | WebSocket registration result |
|
|
255
|
-
| `WEBSOCKET_DEREGISTER_SUCCESS` / `FAIL` | `'Websocket Deregister ...'` | WebSocket deregistration result |
|
|
256
|
-
| `WEBSOCKET_EVENT_RECEIVED` | `'Websocket Event Received'` | WebSocket event received |
|
|
257
|
-
| `UPLOAD_LOGS_SUCCESS` / `FAILED` | `'Upload Logs ...'` | Log upload result |
|
|
258
|
-
|
|
259
|
-
### Data Fetch Events
|
|
260
|
-
|
|
261
|
-
| Constant | Value | Description |
|
|
262
|
-
|----------|-------|-------------|
|
|
263
|
-
| `ENTRYPOINT_FETCH_SUCCESS` / `FAILED` | `'Entrypoint Fetch ...'` | Entry point fetch result |
|
|
264
|
-
| `ADDRESSBOOK_FETCH_SUCCESS` / `FAILED` | `'AddressBook Fetch ...'` | Address book fetch result |
|
|
265
|
-
| `QUEUE_FETCH_SUCCESS` / `FAILED` | `'Queue Fetch ...'` | Queue fetch result |
|
|
266
|
-
| `OUTDIAL_ANI_EP_FETCH_SUCCESS` / `FAILED` | `'Outdial ANI Entries Fetch ...'` | Outdial ANI entries fetch result |
|
|
267
|
-
|
|
268
|
-
---
|
|
269
|
-
|
|
270
|
-
## Behavioral Event Taxonomy
|
|
271
|
-
|
|
272
|
-
Each behavioral event maps to a structured taxonomy in `behavioral-events.ts`:
|
|
273
|
-
|
|
274
|
-
```
|
|
275
|
-
{product}.{agent}.{target}.{verb}
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
- **product**: Always `'wxcc_sdk'` (from `PRODUCT_NAME`)
|
|
279
|
-
- **agent**: `'user'` for user-initiated actions, `'service'` for system-generated events
|
|
280
|
-
- **target**: Snake_case description of the action (e.g., `'station_login'`, `'task_accept'`)
|
|
281
|
-
- **verb**: `'complete'` for success, `'fail'` for failure, `'set'` for RONA events
|
|
282
|
-
|
|
283
|
-
**Example**: `STATION_LOGIN_SUCCESS` maps to `wxcc_sdk.user.station_login.complete`
|
|
284
|
-
|
|
285
|
-
> **Note**: The following events do **not** have behavioral taxonomy mappings in `behavioral-events.ts`:
|
|
286
|
-
> - `WEBSOCKET_DEREGISTER_SUCCESS`
|
|
287
|
-
> - `WEBSOCKET_DEREGISTER_FAIL`
|
|
288
|
-
> - `WEBSOCKET_EVENT_RECEIVED`
|
|
289
|
-
>
|
|
290
|
-
> Calling `trackBehavioralEvent` with these event names will push an event with an `undefined` taxonomy.
|
|
291
|
-
|
|
292
|
-
---
|
|
293
|
-
|
|
294
|
-
## Usage Pattern (timeEvent + trackEvent)
|
|
295
|
-
|
|
296
|
-
The standard pattern used throughout the Contact Center SDK:
|
|
297
|
-
|
|
298
|
-
```typescript
|
|
299
|
-
const metrics = MetricsManager.getInstance();
|
|
300
|
-
|
|
301
|
-
// 1. Start timing before the operation
|
|
302
|
-
metrics.timeEvent([
|
|
303
|
-
METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
|
|
304
|
-
METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
|
|
305
|
-
]);
|
|
306
|
-
|
|
307
|
-
try {
|
|
308
|
-
const response = await performLogin(params);
|
|
309
|
-
|
|
310
|
-
// 2a. Track success (duration_ms auto-added)
|
|
311
|
-
metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {
|
|
312
|
-
...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
|
|
313
|
-
});
|
|
314
|
-
} catch (error) {
|
|
315
|
-
// 2b. Track failure (duration_ms auto-added)
|
|
316
|
-
metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_FAILED, {
|
|
317
|
-
...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error),
|
|
318
|
-
});
|
|
319
|
-
}
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
## Error Handling
|
|
325
|
-
|
|
326
|
-
MetricsManager is designed to be non-blocking. Metric failures do not propagate to callers:
|
|
327
|
-
|
|
328
|
-
- If `webex` is not yet ready, events are queued in `pendingBehavioralEvents`, `pendingOperationalEvents`, or `pendingBusinessEvents`
|
|
329
|
-
- Once `webex.ready` fires, all pending events are flushed
|
|
330
|
-
- If metrics are disabled via `setMetricsDisabled(true)`, all track methods silently return
|
|
331
|
-
- Invalid metric types log an error via `LoggerProxy` but do not throw
|
|
332
|
-
|
|
333
|
-
---
|
|
334
|
-
|
|
335
|
-
## Dependencies
|
|
336
|
-
|
|
337
|
-
- **`@webex/internal-plugin-metrics`**: Provides `webex.internal.newMetrics` for actual metric submission (`submitBehavioralEvent`, `submitOperationalEvent`, `submitBusinessEvent`)
|
|
338
|
-
- **`LoggerProxy`**: Used for error logging within the metrics module
|
|
339
|
-
- **`Failure` type** (from `services/core/GlobalTypes`): Used in `getCommonTrackingFieldForAQMResponseFailed`
|
|
340
|
-
- **`PRODUCT_NAME`** (from `constants.ts`): Set to `'wxcc_sdk'`, used as the product identifier in behavioral taxonomy and as prefix for operational/business event names
|
|
341
|
-
|
|
342
|
-
---
|
|
343
|
-
|
|
344
|
-
## Related
|
|
345
|
-
|
|
346
|
-
- [`MetricsManager.ts`](../MetricsManager.ts) - Singleton metrics manager implementation
|
|
347
|
-
- [`behavioral-events.ts`](../behavioral-events.ts) - Event taxonomy mapping
|
|
348
|
-
- [`constants.ts`](../constants.ts) - `METRIC_EVENT_NAMES` definitions
|
|
349
|
-
- [`../../constants.ts`](../../constants.ts) - `PRODUCT_NAME` constant
|
|
350
|
-
- [`services/core/GlobalTypes.ts`](../../services/core/GlobalTypes.ts) - `Failure` type definition
|