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

package/src/services/agent/ai-docs/AGENTS.md

@@ -0,0 +1,240 @@
+# Agent Service - AI Agent Guide
+
+> **Legacy/reference-only.** Canonical SDD: [`agent-spec.md`](agent-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**: Manage agent lifecycle including login, logout, state changes, and buddy agent queries.
+
+---
+
+## Quick Start
+
+```typescript
+const cc = webex.cc;
+
+// Register and login
+const profile = await cc.register();
+await cc.stationLogin({
+  teamId: profile.teams[0].teamId,
+  loginOption: 'BROWSER',
+});
+
+// Set state to Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Get available agents for transfer
+const buddies = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+```
+
+---
+
+## Key Capabilities
+
+- **Station Login**: Login with browser (WebRTC), extension, or dial number
+- **Station Logout**: Logout from current station with reason
+- **State Management**: Toggle between Available/Idle states with aux codes
+- **Buddy Agents**: Query available agents for consult/transfer
+- **Silent Relogin**: Automatic re-authentication on reconnection
+
+---
+
+## API Reference
+
+### Login Options
+
+| Option | Description | Requires dialNumber |
+|--------|-------------|---------------------|
+| `BROWSER` | WebRTC softphone in browser | No |
+| `EXTENSION` | Desk phone extension | Yes |
+| `AGENT_DN` | Direct dial number | Yes |
+
+### Methods
+
+#### `cc.stationLogin(params)`
+
+Login agent to a station.
+
+**Parameters**:
+- `teamId` (string): Team to login to
+- `loginOption` ('BROWSER' | 'EXTENSION' | 'AGENT_DN'): Device type
+- `dialNumber` (string, optional): Required for EXTENSION/AGENT_DN
+
+**Returns**: `Promise<StationLoginResponse>`
+
+**Example**:
+```typescript
+// Browser login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'BROWSER',
+});
+
+// Extension login
+const response = await cc.stationLogin({
+  teamId: 'team-123',
+  loginOption: 'EXTENSION',
+  dialNumber: '1234',
+});
+```
+
+---
+
+#### `cc.stationLogout(params)`
+
+Logout agent from station.
+
+**Parameters**:
+- `logoutReason` (string, optional): 'User requested logout' | 'Inactivity Logout' | 'User requested agent profile update'
+
+**Returns**: `Promise<StationLogoutResponse>`
+
+**Example**:
+```typescript
+await cc.stationLogout({
+  logoutReason: 'User requested logout',
+});
+```
+
+---
+
+#### `cc.setAgentState(params)`
+
+Change agent state (Available/Idle).
+
+**Parameters**:
+- `state` ('Available' | 'Idle'): New state
+- `auxCodeId` (string): Auxiliary code ID
+- `lastStateChangeReason` (string, optional): Reason for change
+- `agentId` (string, optional): Agent ID (defaults to current agent)
+
+**Returns**: `Promise<SetStateResponse>`
+
+**Example**:
+```typescript
+// Go Available
+await cc.setAgentState({
+  state: 'Available',
+  auxCodeId: '0',
+});
+
+// Go to Idle with specific code
+await cc.setAgentState({
+  state: 'Idle',
+  auxCodeId: 'break-code-123',
+  lastStateChangeReason: 'Coffee break',
+});
+```
+
+---
+
+#### `cc.getBuddyAgents(params)`
+
+Get list of agents for consult/transfer.
+
+**Parameters**:
+- `state` (string, optional): Filter by state ('Available', 'Idle')
+- `mediaType` (string): Media type filter ('telephony', 'chat', 'social', 'email')  
+**Returns**: `Promise<BuddyAgentsResponse>`
+
+**Example**:
+```typescript
+const response = await cc.getBuddyAgents({
+  state: 'Available',
+  mediaType: 'telephony',
+});
+
+response.data.agentList.forEach(agent => {
+  console.log(`${agent.agentName} (${agent.state})`);
+});
+```
+
+---
+
+## Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `agent:stationLoginSuccess` | `StationLoginSuccessResponse` | Login succeeded |
+| `agent:stationLoginFailed` | Error | Login failed |
+| `agent:logoutSuccess` | `LogoutSuccess` | Logout succeeded |
+| `agent:logoutFailed` | Error | Logout failed |
+| `agent:stateChange` | `StateChangeSuccess` | State changed (any source) |
+| `agent:stateChangeSuccess` | `StateChangeSuccess` | State change succeeded |
+| `agent:stateChangeFailed` | Error | State change failed |
+| `agent:multiLogin` | Object | Multi-login detected |
+| `agent:reloginSuccess` | `ReloginSuccess` | Silent relogin succeeded |
+| `agent:dnRegistered` | Object | DN registration complete |
+
+### Event Usage
+
+```typescript
+cc.on('agent:stateChange', (event) => {
+  console.log(`State: ${event.subStatus}, AuxCode: ${event.auxCodeId}`);
+});
+
+cc.on('agent:multiLogin', (event) => {
+  console.warn('Another session detected');
+});
+```
+
+---
+
+## Agent States
+
+The `AgentState` type (`'Available' | 'Idle' | 'RONA' | string`) is extensible -- the `string` union member allows backend-defined states beyond the known values listed below.
+
+| State | SubStatus | Description |
+|-------|-----------|-------------|
+| LoggedIn | Available | Ready to receive tasks |
+| LoggedIn | Idle | On break or not ready (uses aux code for sub-reason) |
+| RONA | - | Rang but no answer; agent failed to accept offered task |
+| LoggedOut | - | Not logged in |
+| LoggedIn | *(custom)* | Additional org-specific states defined via aux codes |
+
+> **Note**: `AgentState` is a union with `string`, so consumers should handle unknown state values gracefully rather than exhaustively matching only the known literals.
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  await cc.stationLogin(params);
+} catch (error) {
+  console.error('Login failed:', error.message);
+  // Access error details
+  if (error.data) {
+    console.error('Field:', error.data.fieldName);
+    console.error('Message:', error.data.message);
+  }
+}
+```
+
+### Common Error Reasons
+
+| Reason | Description |
+|--------|-------------|
+| `DUPLICATE_LOCATION` | Extension/DN already in use |
+| `INVALID_DIAL_NUMBER` | Invalid phone number format |
+| `AGENT_NOT_FOUND` | Agent doesn't exist (silent relogin) |
+
+---
+
+## Dependencies
+
+- Requires `cc.register()` to be called first
+- Agent profile must be fetched before login
+- WebRTC (BROWSER option) requires mercury connection
+
+---
+
+## Related
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive
+- [`cc.ts`](../../../cc.ts) - Main plugin implementation
+- [`types.ts`](../types.ts) - Type definitions

package/src/services/agent/ai-docs/ARCHITECTURE.md

@@ -0,0 +1,304 @@
+# Agent Service - Architecture
+
+> **Legacy/reference-only.** Canonical SDD: [`agent-spec.md`](agent-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 agent lifecycle operations.
+
+---
+
+## Component Overview
+
+| Component       | File                        | Responsibility                                                  |
+| --------------- | --------------------------- | --------------------------------------------------------------- |
+| `ContactCenter` | `src/cc.ts`                 | Plugin class exposing agent methods                             |
+| `routingAgent`  | `services/agent/index.ts`   | AQM request definitions                                         |
+| `Services`      | `services/index.ts`         | Service singleton with agent service                            |
+| `AqmReqs`       | `services/core/aqm-reqs.ts` | HTTP requests to backend; responses via WebSocket notifications |
+
+---
+
+## File Structure
+
+```
+services/agent/
+├── index.ts          # Agent service factory
+├── types.ts          # Agent types and events
+└── ai-docs/
+    ├── AGENTS.md     # Usage documentation
+    └── ARCHITECTURE.md # This file
+```
+
+---
+
+## Service Factory Pattern
+
+The agent service uses a factory pattern:
+
+```typescript
+// services/agent/index.ts
+export default function routingAgent(routing: AqmReqs) {
+  return {
+    stationLogin: routing.req((p: {data: UserStationLogin}) => ({
+      url: '/v1/agents/login',
+      host: WCC_API_GATEWAY,
+      data: p.data,
+      notifSuccess: {
+        bind: {type: CC_EVENTS.AGENT_STATION_LOGIN, ...},
+        msg: {} as StationLoginSuccess,
+      },
+      notifFail: {...},
+    })),
+    logout: routing.req((p: {data: Logout}) => ({...})),
+    stateChange: routing.req((p: {data: StateChange}) => ({...})),
+    buddyAgents: routing.req((p: {data: BuddyAgents}) => ({...})),
+    reload: routing.reqEmpty(() => ({...})),
+  };
+}
+```
+
+---
+
+## Data Flow
+
+### Station Login Flow
+
+```mermaid
+flowchart TD
+    A[cc.stationLogin] --> B[Validate input]
+    B --> C[services.agent.stationLogin]
+    C --> D[AqmReqs.req]
+    D --> E[HTTP REST request to backend]
+    E --> F[Backend processes]
+    F --> G{Success?}
+    G -->|Yes| H[StationLoginSuccess event]
+    G -->|No| I[StationLoginFailed event]
+    H --> J[Register WebCalling if BROWSER]
+    J --> K[Track metrics]
+    K --> L[Return response]
+    I --> M[getErrorDetails]
+    M --> N[Throw error]
+```
+
+---
+
+## Sequence Diagrams
+
+### Station Login
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant CC as ContactCenter
+    participant Svc as Services.agent
+    participant AQM as AqmReqs
+    participant WS as WebSocket
+    participant BE as Backend
+    App->>CC: stationLogin(params)
+    CC->>CC: Validate dial number
+    CC->>CC: timeEvent(LOGIN_SUCCESS, LOGIN_FAILED)
+    CC->>Svc: stationLogin({data})
+    Svc->>AQM: req(config)
+    AQM->>BE: HTTP POST /v1/agents/login
+    BE-->>WS: AgentStationLoginSuccess
+    WS-->>AQM: Resolve with response
+    AQM-->>Svc: Return response
+    Svc-->>CC: Login response
+    CC->>CC: Register WebCalling (if BROWSER)
+    CC->>CC: trackEvent(LOGIN_SUCCESS)
+    CC-->>App: StationLoginResponse
+```
+
+### State Change
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant CC as ContactCenter
+    participant Svc as Services.agent
+    participant WS as WebSocket
+    participant BE as Backend
+
+    App->>CC: setAgentState(params)
+    CC->>CC: timeEvent(STATE_SUCCESS, STATE_FAILED)
+    CC->>Svc: stateChange({data})
+    Svc->>BE: HTTP PUT /v1/agents/session/state
+    BE-->>WS: AgentStateChangeSuccess
+    WS-->>CC: Emit via handleWebsocketMessage
+    CC->>CC: emit(agent:stateChange)
+    CC->>CC: trackEvent(STATE_SUCCESS)
+    CC-->>App: SetStateResponse
+```
+
+---
+
+## Request Configuration
+
+Each agent method defines:
+
+```typescript
+{
+  url: '/v1/agents/...',      // API endpoint
+  host: WCC_API_GATEWAY,      // Base URL
+  data: p.data,               // Request payload
+  method: HTTP_METHODS.POST,  // HTTP method (POST if data present, GET otherwise)
+  err: errorHandler,          // Error transformer
+  notifSuccess: {
+    bind: {
+      type: CC_EVENTS.SUCCESS_TYPE,
+      data: {type: CC_EVENTS.SUCCESS_TYPE},
+    },
+    msg: {} as SuccessType,   // Response type hint
+  },
+  notifFail: {
+    bind: {
+      type: CC_EVENTS.FAIL_TYPE,
+      data: {type: CC_EVENTS.FAIL_TYPE},
+    },
+    errId: 'Service.aqm.agent.method',
+  },
+}
+```
+
+---
+
+## Event Flow
+
+### WebSocket to Application
+
+```mermaid
+flowchart LR
+    A[WebSocket Message] --> B[WebSocketManager]
+    B --> C[cc.handleWebsocketMessage]
+    C --> D{Event Type?}
+    D -->|AGENT_STATE_CHANGE| E[emit agent:stateChange]
+    D -->|data.type check| F{Nested Type?}
+    F -->|STATION_LOGIN_SUCCESS| G[Transform channelsMap]
+    G --> H[emit agent:stationLoginSuccess]
+    F -->|LOGOUT_SUCCESS| I[emit agent:logoutSuccess]
+```
+
+### ChannelsMap Transformation
+
+The login success event transforms `channelsMap` to `mmProfile`:
+
+```typescript
+// Incoming
+channelsMap: {
+  chat: ['channel-1', 'channel-2'],
+  email: ['channel-3'],
+  telephony: ['channel-4'],
+}
+
+// Transformed
+mmProfile: {
+  chat: 2,      // Length of arrays
+  email: 1,
+  social: 0,
+  telephony: 1,
+}
+```
+
+---
+
+## Silent Relogin
+
+Automatic relogin on WebSocket reconnection:
+
+```mermaid
+flowchart TD
+    A[WebSocket Reconnected] --> B[handleConnectionLost]
+    B --> C{allowAutomatedRelogin?}
+    C -->|Yes| D[silentRelogin]
+    D --> E[services.agent.reload]
+    E --> F{Success?}
+    F -->|Yes| G[Update agentConfig]
+    G --> H{lastStateChangeReason?}
+    H -->|agent-wss-disconnect| I[setAgentState Available]
+    H -->|Other| J[Keep current state]
+    F -->|No, AGENT_NOT_FOUND| K[Handle silently]
+    F -->|No, Other| L[Throw error]
+```
+
+---
+
+## Error Handling
+
+### Login Error Details
+
+For `stationLogin`, special error handling extracts field-specific messages:
+
+```typescript
+// Utils.ts - getStationLoginErrorData
+const errorCodeMessageMap = {
+  DUPLICATE_LOCATION: {
+    message: 'This extension is already in use',
+    fieldName: loginOption,
+  },
+  INVALID_DIAL_NUMBER: {
+    message: 'Enter a valid US dial number...',
+    fieldName: loginOption,
+  },
+};
+```
+
+---
+
+## Metrics Tracking
+
+| Metric                       | Type                              | When Tracked             |
+| ---------------------------- | --------------------------------- | ------------------------ |
+| `STATION_LOGIN_SUCCESS`      | behavioral, business, operational | Login succeeds           |
+| `STATION_LOGIN_FAILED`       | behavioral, business, operational | Login fails              |
+| `STATION_LOGOUT_SUCCESS`     | behavioral, business, operational | Logout succeeds          |
+| `STATION_LOGOUT_FAILED`      | behavioral, business, operational | Logout fails             |
+| `AGENT_STATE_CHANGE_SUCCESS` | behavioral, business, operational | State change succeeds    |
+| `AGENT_STATE_CHANGE_FAILED`  | behavioral, business, operational | State change fails       |
+| `FETCH_BUDDY_AGENTS_SUCCESS` | operational                       | Buddy agents fetched     |
+| `FETCH_BUDDY_AGENTS_FAILED`  | operational                       | Buddy agents fetch fails |
+
+---
+
+## Troubleshooting
+
+### Issue: Login fails with DUPLICATE_LOCATION
+
+**Cause**: Extension/DN already in use by another session
+
+**Solution**:
+
+1. Logout from other session
+2. Use different extension
+3. Contact admin if stuck
+
+### Issue: State change fails
+
+**Cause**: Agent may be in a call or transitioning state
+
+**Solution**:
+1. Complete current interaction
+2. Wait for state to stabilize
+3. Retry state change
+
+### Issue: Silent relogin not working
+
+**Cause**: `allowAutomatedRelogin` config not set
+
+**Solution**:
+```typescript
+const webex = Webex.init({
+  config: {
+    cc: {
+      allowAutomatedRelogin: true,
+    },
+  },
+});
+```
+
+---
+
+## Related Files
+
+- [cc.ts](../../../cc.ts) - Main plugin
+- [agent/index.ts](../index.ts) - Service implementation
+- [agent/types.ts](../types.ts) - Type definitions
+- [cc.ts test](../../../../test/unit/spec/cc.ts) - Test file