@webex/contact-center 3.12.0-next.9 → 3.12.0-next.90

package/src/metrics/ai-docs/AGENTS.md

@@ -0,0 +1,350 @@
+# Metrics Module - AI Agent Guide
+
+> **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.
+
+> **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.
+
+---
+
+## Quick Start
+
+```typescript
+import MetricsManager from '../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../metrics/constants';
+
+// Get the singleton instance (webex is set during cc.register())
+const metrics = MetricsManager.getInstance();
+
+// Time an operation, then track its result
+metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
+// ... perform the operation ...
+metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
+```
+
+---
+
+## Key Capabilities
+
+- **Singleton Pattern**: Single `MetricsManager` instance shared across the entire SDK
+- **Three Metric Types**: Behavioral (user actions), operational (system events), business (business-level analytics)
+- **Event Timing**: `timeEvent` + `trackEvent` pattern automatically calculates `duration_ms`
+- **Queued Submission**: Events are queued until the Webex SDK is ready, then submitted in order
+- **Behavioral Taxonomy**: Structured `product.agent.target.verb` naming convention for behavioral events
+- **Payload Preparation**: Automatic cleanup of empty fields, space-to-underscore conversion, and `tabHidden` metadata
+- **AQM Response Helpers**: Static methods to extract common tracking fields from AQM responses
+
+---
+
+## API Reference
+
+### Methods
+
+#### `MetricsManager.getInstance(options?)`
+
+Returns the singleton instance. On first call with `{webex}`, binds to the Webex SDK and begins listening for the `ready` event.
+
+**Parameters**:
+- `options` (object, optional): `{webex: WebexSDK}` - The Webex SDK instance
+
+**Returns**: `MetricsManager`
+
+**Example**:
+```typescript
+// During initialization (called internally by cc.register())
+const metrics = MetricsManager.getInstance({webex});
+
+// Subsequent calls (no webex needed)
+const metrics = MetricsManager.getInstance();
+```
+
+---
+
+#### `metrics.timeEvent(keys)`
+
+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.
+
+**Parameters**:
+- `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.
+
+**Returns**: `void`
+
+**Example**:
+```typescript
+// Single key
+metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
+
+// Multiple keys (success/failure share one timer)
+metrics.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+```
+
+---
+
+#### `metrics.trackEvent(name, payload?, metricServices?)`
+
+Tracks an event across one or more metric services.
+
+**Parameters**:
+- `name` (METRIC_EVENT_NAMES): The event name constant
+- `payload` (EventPayload, optional): Key-value pairs of event data
+- `metricServices` (MetricsType[], optional): Array of `'behavioral'` | `'operational'` | `'business'` (default: `['behavioral']`)
+
+**Returns**: `void`
+
+**Example**:
+```typescript
+// Behavioral only (default)
+metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
+
+// Multiple services
+metrics.trackEvent(
+  METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+  {interactionId: 'abc'},
+  ['behavioral', 'operational']
+);
+```
+
+---
+
+#### `metrics.trackBehavioralEvent(name, options?)`
+
+Tracks a single behavioral event. Looks up the event taxonomy from `behavioral-events.ts` and submits via `webex.internal.newMetrics.submitBehavioralEvent`.
+
+**Parameters**:
+- `name` (METRIC_EVENT_NAMES): The event name
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+---
+
+#### `metrics.trackOperationalEvent(name, options?)`
+
+Tracks a single operational event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitOperationalEvent`.
+
+**Parameters**:
+- `name` (METRIC_EVENT_NAMES): The event name
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+---
+
+#### `metrics.trackBusinessEvent(name, options?)`
+
+Tracks a single business event. Prefixes the event name with `WXCC_SDK_` and submits via `webex.internal.newMetrics.submitBusinessEvent` with `appType: 'wxcc_sdk'`.
+
+**Parameters**:
+- `name` (METRIC_EVENT_NAMES): The event name
+- `options` (EventPayload, optional): Additional payload data
+
+**Returns**: `void`
+
+---
+
+#### `metrics.setMetricsDisabled(disabled)`
+
+Enables or disables metrics collection. When disabled, all pending events are cleared and new events are dropped.
+
+**Parameters**:
+- `disabled` (boolean): `true` to disable, `false` to enable
+
+**Returns**: `void`
+
+---
+
+#### `MetricsManager.getCommonTrackingFieldForAQMResponse(response)`
+
+Static helper that extracts common tracking fields from an AQM success response.
+
+**Parameters**:
+- `response` (any): The AQM response object
+
+**Returns**: `Record<string, any>` with fields: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
+
+**Example**:
+```typescript
+const fields = MetricsManager.getCommonTrackingFieldForAQMResponse(aqmResponse);
+metrics.trackEvent(METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS, {
+  ...fields,
+  interactionId: task.interactionId,
+});
+```
+
+---
+
+#### `MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failureResponse)`
+
+Static helper that extracts common tracking fields from an AQM failure response.
+
+**Parameters**:
+- `failureResponse` (Failure): The AQM failure response object
+
+**Returns**: `Record<string, any>` with fields: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
+
+---
+
+#### `MetricsManager.resetInstance()`
+
+Resets the singleton instance. Used for testing only.
+
+**Returns**: `void`
+
+---
+
+## Metric Event Names
+
+All event names are defined in `METRIC_EVENT_NAMES` (`constants.ts`). Events follow a `<Category> <Action> <Result>` pattern.
+
+### Agent Events
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `STATION_LOGIN_SUCCESS` | `'Station Login Success'` | Agent station login succeeded |
+| `STATION_LOGIN_FAILED` | `'Station Login Failed'` | Agent station login failed |
+| `STATION_LOGOUT_SUCCESS` | `'Station Logout Success'` | Agent station logout succeeded |
+| `STATION_LOGOUT_FAILED` | `'Station Logout Failed'` | Agent station logout failed |
+| `STATION_RELOGIN_SUCCESS` | `'Station Relogin Success'` | Silent relogin succeeded |
+| `STATION_RELOGIN_FAILED` | `'Station Relogin Failed'` | Silent relogin failed |
+| `AGENT_STATE_CHANGE_SUCCESS` | `'Agent State Change Success'` | State change succeeded |
+| `AGENT_STATE_CHANGE_FAILED` | `'Agent State Change Failed'` | State change failed |
+| `FETCH_BUDDY_AGENTS_SUCCESS` | `'Fetch Buddy Agents Success'` | Buddy agents fetch succeeded |
+| `FETCH_BUDDY_AGENTS_FAILED` | `'Fetch Buddy Agents Failed'` | Buddy agents fetch failed |
+| `AGENT_RONA` | `'Agent RONA'` | Agent Ring-On-No-Answer triggered |
+| `AGENT_CONTACT_ASSIGN_FAILED` | `'Agent Contact Assign Failed'` | Contact assignment failed |
+| `AGENT_INVITE_FAILED` | `'Agent Invite Failed'` | Agent invite failed |
+| `AGENT_DEVICE_TYPE_UPDATE_SUCCESS` | `'Agent Device Type Update Success'` | Device type update succeeded |
+| `AGENT_DEVICE_TYPE_UPDATE_FAILED` | `'Agent Device Type Update Failed'` | Device type update failed |
+
+### Task Events
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `TASK_ACCEPT_SUCCESS` / `FAILED` | `'Task Accept ...'` | Task accept result |
+| `TASK_DECLINE_SUCCESS` / `FAILED` | `'Task Decline ...'` | Task decline result |
+| `TASK_END_SUCCESS` / `FAILED` | `'Task End ...'` | Task end result |
+| `TASK_WRAPUP_SUCCESS` / `FAILED` | `'Task Wrapup ...'` | Task wrapup result |
+| `TASK_HOLD_SUCCESS` / `FAILED` | `'Task Hold ...'` | Task hold result |
+| `TASK_RESUME_SUCCESS` / `FAILED` | `'Task Resume ...'` | Task resume result |
+| `TASK_CONSULT_START_SUCCESS` / `FAILED` | `'Task Consult Start ...'` | Consult start result |
+| `TASK_CONSULT_END_SUCCESS` / `FAILED` | `'Task Consult End ...'` | Consult end result |
+| `TASK_TRANSFER_SUCCESS` / `FAILED` | `'Task Transfer ...'` | Transfer result |
+| `TASK_PAUSE_RECORDING_SUCCESS` / `FAILED` | `'Task Pause Recording ...'` | Pause recording result |
+| `TASK_RESUME_RECORDING_SUCCESS` / `FAILED` | `'Task Resume Recording ...'` | Resume recording result |
+| `TASK_ACCEPT_CONSULT_SUCCESS` / `FAILED` | `'Task Accept Consult ...'` | Accept consult result |
+| `TASK_AUTO_ANSWER_SUCCESS` / `FAILED` | `'Task Auto Answer ...'` | Auto-answer result |
+| `TASK_OUTDIAL_SUCCESS` / `FAILED` | `'Task Outdial ...'` | Outdial result |
+
+### Conference Events
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `TASK_CONFERENCE_START_SUCCESS` / `FAILED` | `'Task Conference Start ...'` | Conference start result |
+| `TASK_CONFERENCE_END_SUCCESS` / `FAILED` | `'Task Conference End ...'` | Conference end result |
+| `TASK_CONFERENCE_TRANSFER_SUCCESS` / `FAILED` | `'Task Conference Transfer ...'` | Conference transfer result |
+| `TASK_CONFERENCE_EXIT_SUCCESS` / `FAILED` | `'Task Conference Exit ...'` | Conference exit result |
+| `TASK_SWITCH_CALL_SUCCESS` / `FAILED` | `'Task Switch Call ...'` | Switch call result |
+
+### System Events
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `WEBSOCKET_REGISTER_SUCCESS` / `FAILED` | `'Websocket Register ...'` | WebSocket registration result |
+| `WEBSOCKET_DEREGISTER_SUCCESS` / `FAIL` | `'Websocket Deregister ...'` | WebSocket deregistration result |
+| `WEBSOCKET_EVENT_RECEIVED` | `'Websocket Event Received'` | WebSocket event received |
+| `UPLOAD_LOGS_SUCCESS` / `FAILED` | `'Upload Logs ...'` | Log upload result |
+
+### Data Fetch Events
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `ENTRYPOINT_FETCH_SUCCESS` / `FAILED` | `'Entrypoint Fetch ...'` | Entry point fetch result |
+| `ADDRESSBOOK_FETCH_SUCCESS` / `FAILED` | `'AddressBook Fetch ...'` | Address book fetch result |
+| `QUEUE_FETCH_SUCCESS` / `FAILED` | `'Queue Fetch ...'` | Queue fetch result |
+| `OUTDIAL_ANI_EP_FETCH_SUCCESS` / `FAILED` | `'Outdial ANI Entries Fetch ...'` | Outdial ANI entries fetch result |
+
+---
+
+## Behavioral Event Taxonomy
+
+Each behavioral event maps to a structured taxonomy in `behavioral-events.ts`:
+
+```
+{product}.{agent}.{target}.{verb}
+```
+
+- **product**: Always `'wxcc_sdk'` (from `PRODUCT_NAME`)
+- **agent**: `'user'` for user-initiated actions, `'service'` for system-generated events
+- **target**: Snake_case description of the action (e.g., `'station_login'`, `'task_accept'`)
+- **verb**: `'complete'` for success, `'fail'` for failure, `'set'` for RONA events
+
+**Example**: `STATION_LOGIN_SUCCESS` maps to `wxcc_sdk.user.station_login.complete`
+
+> **Note**: The following events do **not** have behavioral taxonomy mappings in `behavioral-events.ts`:
+> - `WEBSOCKET_DEREGISTER_SUCCESS`
+> - `WEBSOCKET_DEREGISTER_FAIL`
+> - `WEBSOCKET_EVENT_RECEIVED`
+>
+> Calling `trackBehavioralEvent` with these event names will push an event with an `undefined` taxonomy.
+
+---
+
+## Usage Pattern (timeEvent + trackEvent)
+
+The standard pattern used throughout the Contact Center SDK:
+
+```typescript
+const metrics = MetricsManager.getInstance();
+
+// 1. Start timing before the operation
+metrics.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+
+try {
+  const response = await performLogin(params);
+
+  // 2a. Track success (duration_ms auto-added)
+  metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
+  });
+} catch (error) {
+  // 2b. Track failure (duration_ms auto-added)
+  metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_FAILED, {
+    ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(error),
+  });
+}
+```
+
+---
+
+## Error Handling
+
+MetricsManager is designed to be non-blocking. Metric failures do not propagate to callers:
+
+- If `webex` is not yet ready, events are queued in `pendingBehavioralEvents`, `pendingOperationalEvents`, or `pendingBusinessEvents`
+- Once `webex.ready` fires, all pending events are flushed
+- If metrics are disabled via `setMetricsDisabled(true)`, all track methods silently return
+- Invalid metric types log an error via `LoggerProxy` but do not throw
+
+---
+
+## Dependencies
+
+- **`@webex/internal-plugin-metrics`**: Provides `webex.internal.newMetrics` for actual metric submission (`submitBehavioralEvent`, `submitOperationalEvent`, `submitBusinessEvent`)
+- **`LoggerProxy`**: Used for error logging within the metrics module
+- **`Failure` type** (from `services/core/GlobalTypes`): Used in `getCommonTrackingFieldForAQMResponseFailed`
+- **`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
+
+---
+
+## Related
+
+- [`MetricsManager.ts`](../MetricsManager.ts) - Singleton metrics manager implementation
+- [`behavioral-events.ts`](../behavioral-events.ts) - Event taxonomy mapping
+- [`constants.ts`](../constants.ts) - `METRIC_EVENT_NAMES` definitions
+- [`../../constants.ts`](../../constants.ts) - `PRODUCT_NAME` constant
+- [`services/core/GlobalTypes.ts`](../../services/core/GlobalTypes.ts) - `Failure` type definition

package/src/metrics/ai-docs/ARCHITECTURE.md

@@ -0,0 +1,338 @@
+# Metrics Module - Architecture
+
+> **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.
+
+> **Purpose**: Technical documentation for the metrics collection, batching, and submission system within the Contact Center SDK.
+
+---
+
+## Component Overview
+
+| Component                | File                    | Responsibility                                                                 |
+| ------------------------ | ----------------------- | ------------------------------------------------------------------------------ |
+| `MetricsManager`         | `MetricsManager.ts`     | Singleton that manages event queuing, timing, payload preparation, and submission |
+| `BehavioralEventTaxonomy`| `behavioral-events.ts`  | Maps metric event names to structured taxonomy for behavioral analytics         |
+| `METRIC_EVENT_NAMES`     | `constants.ts`          | Canonical constant object of all tracked metric event names                     |
+
+---
+
+## File Structure
+
+```
+src/metrics/
+├── MetricsManager.ts       # Singleton metrics manager
+├── behavioral-events.ts    # Behavioral event taxonomy mapping
+├── constants.ts            # METRIC_EVENT_NAMES constants
+└── ai-docs/
+    ├── AGENTS.md           # Usage documentation (see PR #4762)
+    └── ARCHITECTURE.md     # This file
+```
+
+---
+
+## Singleton Pattern
+
+`MetricsManager` uses a private constructor with a static `getInstance` factory:
+
+```typescript
+// MetricsManager.ts
+export default class MetricsManager {
+  private static instance: MetricsManager;
+  private constructor() {}
+
+  public static getInstance(options?: {webex: WebexSDK}): MetricsManager {
+    if (!MetricsManager.instance) {
+      MetricsManager.instance = new MetricsManager();
+    }
+    if (!MetricsManager.instance.webex && options?.webex) {
+      MetricsManager.instance.setWebex(options.webex);
+    }
+    return MetricsManager.instance;
+  }
+
+  public static resetInstance() {
+    MetricsManager.instance = undefined;
+  }
+}
+```
+
+- The Webex SDK instance is set once via `setWebex()`, which listens for the `ready` event before flushing pending queues.
+- `resetInstance()` sets the singleton to `undefined`, allowing a fresh instance to be created. Primarily used in tests.
+
+---
+
+## Data Flow
+
+### Event Submission Flow
+
+```mermaid
+flowchart TD
+    A[cc.ts calls metricsManager.timeEvent] --> B[Store startTime + keys in runningEvents]
+    B --> C[Operation executes]
+    C --> D{Success or Failure?}
+    D -->|Success| E[cc.ts calls metricsManager.trackEvent with success name]
+    D -->|Failure| F[cc.ts calls metricsManager.trackEvent with failure name]
+    E --> G[addDurationIfTimed attaches duration_ms]
+    F --> G
+    G --> H[preparePayload cleans and enriches]
+    H --> I{Metric type?}
+    I -->|behavioral| J[Push to pendingBehavioralEvents]
+    I -->|operational| K[Push to pendingOperationalEvents]
+    I -->|business| L[Push to pendingBusinessEvents]
+    J --> M[submitPendingBehavioralEvents]
+    K --> N[submitPendingOperationalEvents]
+    L --> O[submitPendingBusinessEvents]
+    M --> P[webex.internal.newMetrics.submitBehavioralEvent]
+    N --> Q[webex.internal.newMetrics.submitOperationalEvent]
+    O --> R[webex.internal.newMetrics.submitBusinessEvent]
+```
+
+---
+
+## Sequence Diagrams
+
+### Track Event with Timing
+
+```mermaid
+sequenceDiagram
+    participant CC as ContactCenter (cc.ts)
+    participant MM as MetricsManager
+    participant NM as webex.internal.newMetrics
+
+    CC->>MM: timeEvent([SUCCESS_KEY, FAILURE_KEY])
+    Note over MM: Store startTime + key set in runningEvents
+    CC->>CC: Execute operation (e.g., stationLogin)
+    Note over MM: trackEvent defaults to ['behavioral'] only if no metricServices specified
+    alt Success
+        CC->>MM: trackEvent(SUCCESS_KEY, payload, ['behavioral', 'operational', 'business'])
+    else Failure
+        CC->>MM: trackEvent(FAILURE_KEY, payload, ['behavioral', 'operational', 'business'])
+    end
+    MM->>MM: addDurationIfTimed → attach duration_ms
+    MM->>MM: preparePayload → clean empty fields, add tabHidden
+    loop For each metric type
+        MM->>MM: Push to pending queue
+        alt readyToSubmitEvents
+            MM->>NM: submit[Behavioral|Operational|Business]Event
+        else not ready
+            Note over MM: Events stay queued until SDK ready
+        end
+    end
+```
+
+### Initialization and Readiness
+
+```mermaid
+sequenceDiagram
+    participant CC as ContactCenter
+    participant MM as MetricsManager
+    participant Webex as WebexSDK
+
+    CC->>MM: getInstance({webex})
+    MM->>MM: Create singleton (if needed)
+    MM->>MM: setWebex(webex)
+    opt webex.ready === true
+        MM->>MM: setReadyToSubmitEvents()
+        MM->>MM: submitPendingEvents()
+    end
+    MM->>Webex: webex.once('ready', callback)
+    Note over MM: 'ready' listener is always registered
+    Webex-->>MM: 'ready' event fires
+    MM->>MM: setReadyToSubmitEvents()
+    MM->>MM: submitPendingEvents()
+```
+
+---
+
+## Behavioral Event Taxonomy
+
+Each metric event name maps to a `BehavioralEventTaxonomy` with four fields:
+
+```typescript
+type BehavioralEventTaxonomy = {
+  product: MetricEventProduct;  // Always PRODUCT_NAME ('wxcc_sdk')
+  agent: MetricEventAgent;      // 'user' or 'service'
+  target: string;               // e.g., 'station_login', 'task_accept'
+  verb: MetricEventVerb;        // 'complete' for success, 'fail' for failure
+};
+```
+
+The final behavioral event name is constructed as: `{product}.{agent}.{target}.{verb}`
+
+Example: `wxcc_sdk.user.station_login.complete`
+
+The mapping is defined in `behavioral-events.ts` via `eventTaxonomyMap` and accessed through `getEventTaxonomy(name)`.
+
+---
+
+## Event Queuing and Submission
+
+### Three Parallel Queues
+
+MetricsManager maintains three independent pending event queues:
+
+| Queue                       | Type         | Submitted Via                                      | Name Transform                                  | Extra Metadata                   |
+| --------------------------- | ------------ | -------------------------------------------------- | ----------------------------------------------- | -------------------------------- |
+| `pendingBehavioralEvents`   | behavioral   | `webex.internal.newMetrics.submitBehavioralEvent`   | Taxonomy-based (`{product}.{agent}.{target}.{verb}`) | None                             |
+| `pendingOperationalEvents`  | operational  | `webex.internal.newMetrics.submitOperationalEvent`  | `WXCC_SDK_` prefix + uppercase (e.g. `WXCC_SDK_STATION_LOGIN_SUCCESS`) | None                             |
+| `pendingBusinessEvents`     | business     | `webex.internal.newMetrics.submitBusinessEvent`     | `WXCC_SDK_` prefix + uppercase (same as operational) | `metadata: {appType: 'wxcc_sdk'}` |
+
+### Submission Guards
+
+- **readyToSubmitEvents**: Set to `true` only after `webex.once('ready')` fires. Events queue until then.
+- **submittingEvents**: Lock flag to prevent concurrent `submitPendingEvents()` calls.
+- **metricsDisabled**: When `true`, all `track*` methods return early and `clearPendingEvents()` empties all queues.
+
+---
+
+## Timing Pattern (`timeEvent` / `trackEvent`)
+
+```mermaid
+flowchart LR
+    A[timeEvent keys] --> B[runningEvents stores startTime + key Set]
+    B --> C[trackEvent called with one of the keys]
+    C --> D[addDurationIfTimed matches key]
+    D --> E[Calculates duration_ms = now - startTime]
+    E --> F[Removes all keys for that operation]
+    F --> G[Attaches duration_ms to payload]
+```
+
+Usage pattern from `cc.ts`:
+
+```typescript
+// Before operation
+this.metricsManager.timeEvent([
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+]);
+
+// On success
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
+  { ...MetricsManager.getCommonTrackingFieldForAQMResponse(resp) },
+  ['behavioral', 'operational', 'business']
+);
+
+// On failure
+this.metricsManager.trackEvent(
+  METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
+  { ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure) },
+  ['behavioral', 'operational', 'business']
+);
+```
+
+---
+
+## Payload Preparation
+
+`preparePayload()` processes every event payload before submission:
+
+1. **Removes empty/null/undefined fields** — strips keys with `undefined`, `null`, `''`, any arrays, or empty objects
+2. **Converts spaces to underscores** — `spacesToUnderscore()` applied to all key names
+3. **Adds common metadata** — appends `tabHidden: document.hidden` in browser environments
+
+---
+
+## Error Handling Strategy
+
+MetricsManager does not throw errors to callers. Instead:
+
+- Invalid metric types are logged via `LoggerProxy.error`
+- Empty `timeEvent` key arrays are logged and ignored
+- Disabled state (`metricsDisabled`) silently drops events
+- The `submittingEvents` lock prevents race conditions during concurrent submissions
+
+---
+
+## Common Tracking Field Extraction
+
+Two static helpers extract standardized fields from AQM responses for metric payloads:
+
+### `getCommonTrackingFieldForAQMResponse(response)`
+
+Extracts: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
+
+### `getCommonTrackingFieldForAQMResponseFailed(failureResponse)`
+
+Extracts: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
+
+---
+
+## Metric Event Names
+
+All event names are defined in `constants.ts` as `METRIC_EVENT_NAMES`. Events follow a `{Domain} {Action} {Success|Failed}` naming convention:
+
+| Category               | Success Event                          | Failure Event                          |
+| ---------------------- | -------------------------------------- | -------------------------------------- |
+| Station Login          | `STATION_LOGIN_SUCCESS`                | `STATION_LOGIN_FAILED`                 |
+| Station Logout         | `STATION_LOGOUT_SUCCESS`               | `STATION_LOGOUT_FAILED`                |
+| Station Relogin        | `STATION_RELOGIN_SUCCESS`              | `STATION_RELOGIN_FAILED`               |
+| State Change           | `AGENT_STATE_CHANGE_SUCCESS`           | `AGENT_STATE_CHANGE_FAILED`            |
+| Buddy Agents           | `FETCH_BUDDY_AGENTS_SUCCESS`           | `FETCH_BUDDY_AGENTS_FAILED`            |
+| WebSocket Register     | `WEBSOCKET_REGISTER_SUCCESS`           | `WEBSOCKET_REGISTER_FAILED`            |
+| Task Accept            | `TASK_ACCEPT_SUCCESS`                  | `TASK_ACCEPT_FAILED`                   |
+| Task Decline           | `TASK_DECLINE_SUCCESS`                 | `TASK_DECLINE_FAILED`                  |
+| Task End               | `TASK_END_SUCCESS`                     | `TASK_END_FAILED`                      |
+| Task Wrapup            | `TASK_WRAPUP_SUCCESS`                  | `TASK_WRAPUP_FAILED`                   |
+| Task Hold              | `TASK_HOLD_SUCCESS`                    | `TASK_HOLD_FAILED`                     |
+| Task Resume            | `TASK_RESUME_SUCCESS`                  | `TASK_RESUME_FAILED`                   |
+| Task Consult Start     | `TASK_CONSULT_START_SUCCESS`           | `TASK_CONSULT_START_FAILED`            |
+| Task Consult End       | `TASK_CONSULT_END_SUCCESS`             | `TASK_CONSULT_END_FAILED`              |
+| Task Transfer          | `TASK_TRANSFER_SUCCESS`                | `TASK_TRANSFER_FAILED`                 |
+| Task Resume Recording  | `TASK_RESUME_RECORDING_SUCCESS`        | `TASK_RESUME_RECORDING_FAILED`         |
+| Task Pause Recording   | `TASK_PAUSE_RECORDING_SUCCESS`         | `TASK_PAUSE_RECORDING_FAILED`          |
+| Task Accept Consult    | `TASK_ACCEPT_CONSULT_SUCCESS`          | `TASK_ACCEPT_CONSULT_FAILED`           |
+| Task Auto Answer       | `TASK_AUTO_ANSWER_SUCCESS`             | `TASK_AUTO_ANSWER_FAILED`              |
+| Conference Start       | `TASK_CONFERENCE_START_SUCCESS`        | `TASK_CONFERENCE_START_FAILED`         |
+| Conference End         | `TASK_CONFERENCE_END_SUCCESS`          | `TASK_CONFERENCE_END_FAILED`           |
+| Conference Transfer    | `TASK_CONFERENCE_TRANSFER_SUCCESS`     | `TASK_CONFERENCE_TRANSFER_FAILED`      |
+| Conference Exit        | `TASK_CONFERENCE_EXIT_SUCCESS`         | `TASK_CONFERENCE_EXIT_FAILED`          |
+| Switch Call            | `TASK_SWITCH_CALL_SUCCESS`             | `TASK_SWITCH_CALL_FAILED`              |
+| Outdial                | `TASK_OUTDIAL_SUCCESS`                 | `TASK_OUTDIAL_FAILED`                  |
+| Upload Logs            | `UPLOAD_LOGS_SUCCESS`                  | `UPLOAD_LOGS_FAILED`                   |
+| WebSocket Deregister   | `WEBSOCKET_DEREGISTER_SUCCESS`         | `WEBSOCKET_DEREGISTER_FAIL`            |
+| Device Type Update     | `AGENT_DEVICE_TYPE_UPDATE_SUCCESS`     | `AGENT_DEVICE_TYPE_UPDATE_FAILED`      |
+| EntryPoint             | `ENTRYPOINT_FETCH_SUCCESS`             | `ENTRYPOINT_FETCH_FAILED`              |
+| AddressBook            | `ADDRESSBOOK_FETCH_SUCCESS`            | `ADDRESSBOOK_FETCH_FAILED`             |
+| Queue                  | `QUEUE_FETCH_SUCCESS`                  | `QUEUE_FETCH_FAILED`                   |
+| Outdial ANI Entries    | `OUTDIAL_ANI_EP_FETCH_SUCCESS`         | `OUTDIAL_ANI_EP_FETCH_FAILED`          |
+
+Special events (no success/failure pair):
+- `AGENT_RONA` — has behavioral taxonomy (`service.agent_rona.set`)
+- `AGENT_CONTACT_ASSIGN_FAILED` — has behavioral taxonomy (`service.agent_contact_assign.fail`)
+- `AGENT_INVITE_FAILED` — has behavioral taxonomy (`service.agent_invite.fail`)
+- `WEBSOCKET_EVENT_RECEIVED` — **no** behavioral taxonomy (not in `eventTaxonomyMap`)
+
+Events **without** behavioral taxonomy (not in `eventTaxonomyMap`): `WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, `WEBSOCKET_EVENT_RECEIVED`
+
+---
+
+## Troubleshooting
+
+### Issue: Metrics not being submitted
+
+**Cause**: Webex SDK not yet ready when `trackEvent` is called
+
+**Solution**: Events are automatically queued in `pending*Events` arrays and flushed once `webex.once('ready')` fires. Verify the SDK is initializing correctly.
+
+### Issue: Duration not attached to metric
+
+**Cause**: `timeEvent` was not called before `trackEvent`, or the event name does not match any key in `runningEvents`
+
+**Solution**: Ensure `timeEvent([SUCCESS_KEY, FAILURE_KEY])` is called before the operation, and that the exact `METRIC_EVENT_NAMES` constant is used in both calls.
+
+### Issue: Metrics silently dropped
+
+**Cause**: `metricsDisabled` is set to `true`
+
+**Solution**: Check if `setMetricsDisabled(true)` was called. This clears all pending queues and causes all `track*` methods to return early.
+
+---
+
+## Related Files
+
+- [MetricsManager.ts](../MetricsManager.ts) — Singleton metrics manager
+- [behavioral-events.ts](../behavioral-events.ts) — Event taxonomy mapping
+- [constants.ts](../constants.ts) — METRIC_EVENT_NAMES definitions
+- [cc.ts](../../cc.ts) — Main plugin class (primary consumer)
+- [constants.ts](../../constants.ts) — PRODUCT_NAME used in event prefixing