diff --git a/packages/contact-center/user-state/ai-docs/AGENTS.md b/packages/contact-center/user-state/ai-docs/AGENTS.md new file mode 100644 index 000000000..32dd359c6 --- /dev/null +++ b/packages/contact-center/user-state/ai-docs/AGENTS.md @@ -0,0 +1,381 @@ +# User State Widget + +## Overview + +The User State widget provides a user interface for contact center agents to manage their availability status. It handles agent state transitions (Available, Idle with various reasons), displays state duration timers, and manages idle code selection. The widget integrates with the Webex Contact Center SDK and follows the standard three-layer architecture pattern (Widget → Hook → Component → Store). + +**Package:** `@webex/cc-user-state` + +**Version:** See [package.json](../package.json) + +--- + +## Why and What is This Widget Used For? + +### Purpose + +The User State widget enables contact center agents to: +- **Change their availability state** (Available, Idle, etc.) +- **Select idle codes** for different idle reasons (Break, Lunch, Meeting, etc.) +- **View state duration** with real-time timer display +- **Track idle code duration** separately from overall state duration +- **Receive state change notifications** via callbacks + +### Key Capabilities + +- **State Management**: Toggle between Available and various Idle states +- **Idle Code Support**: Dropdown selection for different idle reasons +- **Real-Time Timers**: Displays elapsed time in current state using Web Worker +- **Dual Timer Support**: Tracks both state duration and idle code duration +- **State Change Callbacks**: Extensible callback for state change events +- **Automatic State Sync**: Syncs state changes with backend via SDK +- **Error Handling**: Comprehensive error boundary with callback support + +--- + +## Examples and Use Cases + +### Getting Started + +#### Basic Usage (React) + +```typescript +import { UserState } from '@webex/cc-user-state'; +import React from 'react'; + +function MyApp() { + const handleStateChange = (newState) => { + console.log('Agent state changed to:', newState); + // Update your application state + }; + + return ( + + ); +} +``` + +#### Web Component Usage + +```html + + + + + + + +``` + +#### With State Change Tracking + +```typescript +import { UserState } from '@webex/cc-user-state'; +import React, { useState } from 'react'; + +function AgentDashboard() { + const [currentState, setCurrentState] = useState(null); + const [stateHistory, setStateHistory] = useState([]); + + const handleStateChange = (newState) => { + setCurrentState(newState); + setStateHistory(prev => [...prev, { + state: newState, + timestamp: new Date() + }]); + console.log('State changed to:', newState.name); + }; + + return ( +
+

Current State: {currentState?.name || 'Unknown'}

+ + +
+

State History

+ {stateHistory.map((entry, idx) => ( +
+ {entry.state.name} - {entry.timestamp.toLocaleString()} +
+ ))} +
+
+ ); +} +``` + +### Common Use Cases + +#### 1. Agent Status Display + +```typescript +// Display agent's current status with timer +import { UserState } from '@webex/cc-user-state'; +import { observer } from 'mobx-react-lite'; +import store from '@webex/cc-store'; + +const AgentStatusPanel = observer(() => { + const { currentState, idleCodes } = store; + + const handleStateChange = (newState) => { + console.log(`Agent changed to: ${newState.name}`); + // Store automatically updates + }; + + return ( +
+

Your Status

+ +

Current: {currentState}

+
+ ); +}); +``` + +#### 2. Supervisor Dashboard Integration + +```typescript +// Track multiple agents' state changes +import { UserState } from '@webex/cc-user-state'; + +function SupervisorDashboard({ agentId }) { + const handleAgentStateChange = (state) => { + // Send state change to analytics + trackAgentState(agentId, state); + + // Update dashboard + updateAgentStatus(agentId, state.name); + + // Check if agent needs assistance + if (state.name === 'Idle' && state.duration > 900) { + notifySupervisor(`Agent ${agentId} idle for 15+ minutes`); + } + }; + + return ; +} +``` + +#### 3. State Change Validation + +```typescript +// Validate state changes before allowing +import { UserState } from '@webex/cc-user-state'; +import store from '@webex/cc-store'; + +function ValidatedUserState() { + const handleStateChange = (newState) => { + // Check if agent has pending tasks + if (newState.name === 'Idle' && store.hasActiveTasks) { + showWarning('Please complete active tasks before going idle'); + // State change will be rejected by store + return; + } + + // Log state change + auditLog('State change', { + agent: store.agentId, + from: store.currentState, + to: newState.name, + timestamp: Date.now() + }); + + console.log('State change approved:', newState); + }; + + return ; +} +``` + +#### 4. Custom Error Handling + +```typescript +import store from '@webex/cc-store'; + +// Set error callback before rendering widget +store.onErrorCallback = (componentName, error) => { + console.error(`Error in ${componentName}:`, error); + + // Notify user + showErrorNotification('Failed to update state. Please try again.'); + + // Send to error tracking + trackError(componentName, error); +}; + +// Widget will call this callback on errors + +``` + +### Integration Patterns + +#### With Agent Desktop + +```typescript +import { UserState } from '@webex/cc-user-state'; +import { observer } from 'mobx-react-lite'; +import store from '@webex/cc-store'; + +const AgentDesktop = observer(() => { + const { isAgentLoggedIn, currentState } = store; + + const handleStateChange = (newState) => { + // Update local UI + updateHeaderStatus(newState.name); + + // Log to analytics + logStateChange(newState); + }; + + if (!isAgentLoggedIn) { + return ; + } + + return ( +
+
+ +
+
+ + +
+
+ ); +}); +``` + +#### With Idle Code Management + +```typescript +import { UserState } from '@webex/cc-user-state'; +import { observer } from 'mobx-react-lite'; +import store from '@webex/cc-store'; + +const StateManager = observer(() => { + const { idleCodes, currentState } = store; + + const handleStateChange = (state) => { + console.log('State changed:', state); + + // Log idle code if applicable + if (state.name !== 'Available' && 'id' in state) { + console.log('Idle code selected:', state.id); + logIdleCode(state.id, state.name); + } + }; + + return ( +
+ + +
+

Available idle codes: {idleCodes.length}

+

Current state: {currentState}

+
+
+ ); +}); +``` + +--- + +## Dependencies + +**Note:** For exact versions, see [package.json](../package.json) + +### Runtime Dependencies + +| Package | Purpose | +|---------|---------| +| `@webex/cc-components` | React UI components | +| `@webex/cc-store` | MobX singleton store for state management | +| `mobx-react-lite` | React bindings for MobX | +| `react-error-boundary` | Error boundary implementation | +| `typescript` | TypeScript support | + +### Peer Dependencies + +| Package | Purpose | +|---------|---------| +| `react` | React framework | +| `react-dom` | React DOM rendering | + +### Development Dependencies + +Key development tools (see [package.json](../package.json) for versions): +- TypeScript +- Jest (testing) +- Webpack (bundling) +- ESLint (linting) + +### External SDK Dependency + +The widget requires the **Webex Contact Center SDK** (`@webex/contact-center`) to be initialized and available through the store. The SDK provides: +- `setAgentState()` - Updates agent state (Available/Idle) +- Agent state events - Notifies on state changes +- Idle code management - Provides available idle codes + +### Web Worker + +The widget uses a **Web Worker** for accurate timer management: +- Runs timer in background thread +- Prevents main thread blocking +- Ensures accurate elapsed time tracking +- Automatically cleaned up on unmount + +--- + +## Props API + +| Prop | Type | Required | Default | Description | +|------|------|----------|---------|-------------| +| `onStateChange` | `(state: IdleCode \| CustomState) => void` | No | - | Callback when agent state changes | + +**State Object:** + +```typescript +// IdleCode (from idle codes list) +interface IdleCode { + id: string; // Idle code ID + name: string; // Display name (e.g., "Break", "Lunch") + // ... other properties +} + +// CustomState (for custom states) +interface CustomState { + developerName: string; + // ... custom properties +} +``` + +--- + +## Installation + +```bash +# Install as part of contact center widgets +yarn add @webex/cc-user-state + +# Or install the entire widgets bundle +yarn add @webex/cc-widgets +``` + +--- + +## Additional Resources + +For detailed component architecture, data flows, and sequence diagrams, see [architecture.md](./architecture.md). + +--- + +_Last Updated: 2025-11-26_ + diff --git a/packages/contact-center/user-state/ai-docs/ARCHITECTURE.md b/packages/contact-center/user-state/ai-docs/ARCHITECTURE.md new file mode 100644 index 000000000..88c53b879 --- /dev/null +++ b/packages/contact-center/user-state/ai-docs/ARCHITECTURE.md @@ -0,0 +1,562 @@ +# User State Widget - Architecture + +## Component Overview + +The User State widget follows the three-layer architecture pattern: **Widget → Hook → Component → Store → SDK**. This architecture separates concerns between state management, business logic, and presentation. The widget uniquely uses a **Web Worker** for accurate timer management. + +### Component Table + +| Layer | Component | File | Config/Props | State | Callbacks | Events | Tests | +|-------|-----------|------|--------------|-------|-----------|--------|-------| +| **Widget** | `UserState` | `src/user-state/index.tsx` | `IUserStateProps` | N/A (passes through) | `onStateChange` | SDK events (via store) | `tests/user-state/index.tsx` | +| **Widget Internal** | `UserStateInternal` | `src/user-state/index.tsx` | `IUserStateProps` | Observes store | Same as above | Same as above | Same | +| **Hook** | `useUserState` | `src/helper.ts` | `UseUserStateProps` | `isSettingAgentStatus`, `elapsedTime`, `lastIdleStateChangeElapsedTime` | `onStateChange` | Web Worker messages | `tests/helper.ts` | +| **Web Worker** | Timer Worker | `src/helper.ts` (inline) | Worker messages | `intervalId`, `intervalId2` (timers) | N/A | `elapsedTime`, `lastIdleStateChangeElapsedTime` | N/A | +| **Component** | `UserStateComponent` | `@webex/cc-components` | `UserStateComponentsProps` | Internal UI state | Inherited from hook | N/A | `@webex/cc-components` tests | +| **Store** | `Store` (singleton) | `@webex/cc-store` | N/A | `idleCodes`, `agentId`, `currentState`, `lastStateChangeTimestamp`, `lastIdleCodeChangeTimestamp`, `customState` | N/A | Agent state change events | `@webex/cc-store` tests | +| **SDK** | `ContactCenter` | `@webex/contact-center` | N/A | N/A | N/A | State change events | SDK tests | + +### SDK Methods & Events Integration + +| Component | SDK Methods Used | SDK Events Subscribed | Store Methods Used | +|-----------|------------------|----------------------|-------------------| +| **useUserState Hook** | `setAgentState()` | Agent state change events | `setCurrentState()`, `setLastStateChangeTimestamp()`, `setLastIdleCodeChangeTimestamp()` | +| **Store** | All SDK methods | All SDK events | N/A | +| **Widget** | N/A (via hook) | N/A (via store) | N/A (via hook) | + +### File Structure + +``` +user-state/ +├── src/ +│ ├── helper.ts # useUserState hook + Web Worker +│ ├── index.ts # Package exports +│ ├── user-state/ +│ │ └── index.tsx # Widget component +│ └── user-state.types.ts # TypeScript types +├── tests/ +│ ├── helper.ts # Hook tests +│ └── user-state/ +│ └── index.tsx # Widget tests +├── ai-docs/ +│ ├── agent.md # Overview, examples, usage +│ └── architecture.md # Architecture documentation +├── dist/ # Build output +├── package.json # Dependencies and scripts +├── tsconfig.json # TypeScript config +├── webpack.config.js # Webpack build config +├── jest.config.js # Jest test config +└── eslint.config.mjs # ESLint config +``` + +--- + +## Data Flows + +### Layer Communication Flow + +The widget follows a unidirectional data flow pattern across layers with Web Worker integration: + +```mermaid +graph TB + subgraph "Presentation Layer" + Widget[UserState Widget] + Component[UserStateComponent] + end + + subgraph "Business Logic Layer" + Hook[useUserState Hook
helper.ts] + end + + subgraph "Background Processing" + Worker[Web Worker
Timer] + end + + subgraph "State Management Layer" + Store[Store Singleton] + end + + subgraph "SDK Layer" + SDK[Contact Center SDK] + end + + Widget -->|Props
callbacks| Hook + Hook -->|Read state
idleCodes, currentState, etc| Store + Hook -->|Call methods
setAgentState| SDK + Store -->|Register callbacks
Manage SDK instance| SDK + Hook <-->|Start/Stop/Reset timer| Worker + + Worker -->|Timer updates
every second| Hook + SDK -->|Events
state changes| Store + Store -->|State changes
observable| Hook + Hook -->|Return state
& handlers & timer| Widget + Widget -->|Props
state, handlers, timer| Component + + style Hook fill:#e1f5ff + style Worker fill:#ffe1e1 + style Store fill:#fff4e1 + style SDK fill:#f0e1ff +``` + +**Hook Responsibilities:** +- Manages timer via Web Worker +- Subscribes to state changes +- Handles state update logic +- Dual timer management +- Error handling + +**Web Worker Responsibilities:** +- Background timer execution +- Two independent timers +- State duration timer +- Idle code duration timer + +**Store Responsibilities:** +- Observable state +- Idle codes list +- Current state tracking +- Timestamps for timers + +### Hook (helper.ts) Details + +**File:** `src/helper.ts` + +The `useUserState` hook is the core business logic layer that: + +1. **Manages Local State:** + - `isSettingAgentStatus` - Loading indicator during state change + - `elapsedTime` - Seconds elapsed in current state + - `lastIdleStateChangeElapsedTime` - Seconds elapsed since idle code change + +2. **Web Worker Management:** + ```typescript + // Initialize Web Worker with inline script + const blob = new Blob([workerScript], {type: 'application/javascript'}); + const workerUrl = URL.createObjectURL(blob); + workerRef.current = new Worker(workerUrl); + + // Start both timers + workerRef.current.postMessage({type: 'start', startTime: Date.now()}); + workerRef.current.postMessage({type: 'startIdleCode', startTime: Date.now()}); + ``` + +3. **Provides Key Functions:** + - `setAgentStatus()` - Updates store with new state (UI trigger) + - `updateAgentState()` - Calls SDK to persist state change (Backend sync) + - `callOnStateChange()` - Invokes callback with current state + +4. **State Change Logic:** + - UI triggers `setAgentStatus()` → Updates store + - Store change triggers `useEffect` → Calls `updateAgentState()` + - `updateAgentState()` → SDK call → Updates timestamps → Timer reset + - Callback invoked with new state object + +5. **Timer Reset Logic:** + - Resets main timer when `lastStateChangeTimestamp` changes + - Resets idle code timer when `lastIdleCodeChangeTimestamp` changes + - Stops idle code timer if timestamp matches state timestamp (Available state) + +### Sequence Diagrams + +#### 1. Widget Initialization & Timer Start + +```mermaid +sequenceDiagram + actor User + participant Widget as UserState Widget + participant Hook as useUserState Hook + participant Worker as Web Worker + participant Component as UserStateComponent + participant Store + + User->>Widget: Load widget + activate Widget + Widget->>Hook: useUserState() + activate Hook + Hook->>Store: Read state + Store-->>Hook: {idleCodes, currentState, timestamps} + Hook->>Worker: Create & initialize + activate Worker + Hook->>Worker: postMessage({type: 'start', startTime}) + Hook->>Worker: postMessage({type: 'startIdleCode', startTime}) + Worker-->>Hook: Worker ready + Hook-->>Widget: {state, handlers, timers} + deactivate Hook + Widget->>Component: Render with state + activate Component + Component->>Component: Display current state + Component->>Component: Display idle codes + Component->>Component: Display timer: 00:00 + Component-->>Widget: UI rendered + deactivate Component + deactivate Widget + + Note over Worker,Component: Timer Updates (Every Second) + Worker->>Worker: Increment timers + Worker->>Hook: postMessage({type: 'elapsedTime', elapsedTime: X}) + activate Hook + Hook->>Hook: setElapsedTime(X) + Hook-->>Component: Updated timer value + deactivate Hook + activate Component + Component->>Component: Display timer: 00:0X + deactivate Component +``` + +--- + +#### 2. State Change Flow + +```mermaid +sequenceDiagram + actor User + participant Component as UserStateComponent + participant Hook as useUserState Hook + participant Store + participant SDK + participant Worker as Web Worker + + User->>Component: Select new state (e.g., "Break") + activate Component + Component->>Hook: setAgentStatus(selectedCode) + activate Hook + Hook->>Store: setCurrentState(selectedCode) + activate Store + Store->>Store: currentState = selectedCode (observable) + Store-->>Hook: State updated + deactivate Store + Hook-->>Component: State change initiated + deactivate Hook + deactivate Component + + Note over Hook,SDK: useEffect Triggered by currentState Change + Hook->>Hook: Detect currentState change + activate Hook + Hook->>Hook: updateAgentState(selectedCode) + Hook->>Hook: setIsSettingAgentStatus(true) + Hook->>SDK: setAgentState({state: 'Idle', auxCodeId, agentId}) + activate SDK + SDK->>SDK: Update agent state in backend + SDK-->>Hook: Success response with timestamps + deactivate SDK + Hook->>Store: setLastStateChangeTimestamp(timestamp) + activate Store + Store->>Store: Update timestamps + Store-->>Hook: Timestamps updated + deactivate Store + Hook->>Hook: setIsSettingAgentStatus(false) + Hook->>Hook: callOnStateChange() + Hook->>Hook: Invoke onStateChange(selectedCode) + Hook-->>Component: State change complete + deactivate Hook + activate Component + Component->>Component: Update UI with new state + deactivate Component + + Note over Hook,Worker: Timer Reset + Hook->>Hook: Detect timestamp change + activate Hook + Hook->>Worker: postMessage({type: 'reset', startTime}) + activate Worker + Worker->>Worker: Clear old interval + Worker->>Worker: Start new interval + Worker-->>Hook: Timer reset + deactivate Worker + Hook-->>Component: Timer reset to 00:00 + deactivate Hook + activate Component + Component->>Component: Display timer: 00:00 + deactivate Component +``` + +--- + +#### 3. Custom State Change Flow + +```mermaid +sequenceDiagram + actor User + participant Component as UserStateComponent + participant Hook as useUserState Hook + participant Store + + User->>Component: External state change + activate Component + Component->>Component: (State managed externally) + deactivate Component + + Store->>Store: customState updated (external) + activate Store + Store-->>Hook: customState change (observable) + deactivate Store + + Note over Hook: useEffect Triggered by customState Change + Hook->>Hook: Detect customState change + activate Hook + Hook->>Hook: callOnStateChange() + Hook->>Hook: Check if customState has developerName + + alt customState has developerName + Hook->>Hook: onStateChange(customState) + else no developerName + Hook->>Hook: Find matching idle code + Hook->>Hook: onStateChange(matchingCode) + end + + Hook-->>Component: Callback invoked + deactivate Hook + activate Component + Component->>Component: Handle custom state + deactivate Component +``` + +--- + +#### 4. Cleanup & Worker Termination + +```mermaid +sequenceDiagram + actor User + participant Widget as UserState Widget + participant Hook as useUserState Hook + participant Worker as Web Worker + + User->>Widget: Unmount widget + activate Widget + Widget->>Hook: Cleanup (useEffect return) + activate Hook + Hook->>Worker: postMessage({type: 'stop'}) + activate Worker + Worker->>Worker: clearInterval(intervalId) + Worker-->>Hook: Timer stopped + deactivate Worker + Hook->>Worker: postMessage({type: 'stopIdleCode'}) + activate Worker + Worker->>Worker: clearInterval(intervalId2) + Worker-->>Hook: Idle timer stopped + deactivate Worker + Hook->>Worker: terminate() + activate Worker + Worker->>Worker: Cleanup resources + Worker-->>Hook: Worker terminated + deactivate Worker + Hook->>Hook: workerRef.current = null + Hook-->>Widget: Cleanup complete + deactivate Hook + Widget-->>User: Widget unmounted + deactivate Widget +``` + +--- + +## Troubleshooting Guide + +### Common Issues + +#### 1. Timer Not Updating + +**Symptoms:** +- Timer shows 00:00 and doesn't increment +- Timer freezes after state change + +**Possible Causes:** +- Web Worker failed to initialize +- Browser doesn't support Web Workers +- Worker messages not being received + +**Solutions:** + +```typescript +// Check if Web Worker is supported +if (typeof Worker === 'undefined') { + console.error('Web Workers not supported in this browser'); +} + +// Verify worker initialization in console +console.log('Worker ref:', workerRef.current); + +// Check worker messages +workerRef.current.onmessage = (event) => { + console.log('Worker message:', event.data); +}; + +// Manually trigger timer update for testing +store.setLastStateChangeTimestamp(Date.now()); +``` + +#### 2. State Change Not Persisting + +**Symptoms:** +- UI shows new state but reverts back +- SDK call fails silently +- `isSettingAgentStatus` stays true + +**Possible Causes:** +- SDK not initialized +- Invalid state or idle code +- Network issues +- Agent not logged in + +**Solutions:** + +```typescript +// Check SDK instance +console.log('CC instance:', store.cc); + +// Verify agent is logged in +console.log('Agent logged in:', store.isAgentLoggedIn); + +// Check current state +console.log('Current state:', store.currentState); + +// Check idle codes availability +console.log('Idle codes:', store.idleCodes); + +// Enable detailed logging +store.logger.setLevel('debug'); +``` + +#### 3. Idle Codes Not Displaying + +**Symptoms:** +- Dropdown is empty +- No idle codes available +- Only "Available" shows + +**Possible Causes:** +- Idle codes not loaded from backend +- Store not initialized properly +- Configuration issue + +**Solutions:** + +```typescript +// Check idle codes in store +import store from '@webex/cc-store'; +console.log('Idle codes:', store.idleCodes); +console.log('Idle codes count:', store.idleCodes.length); + +// Verify store initialization +console.log('Store initialized:', store.cc !== undefined); + +// Check agent configuration +console.log('Agent config:', store.cc?.agentConfig); +``` + +#### 4. Callback Not Firing + +**Symptoms:** +- `onStateChange` not called +- No notification on state change +- State changes but app doesn't update + +**Possible Causes:** +- Callback not provided +- Callback reference changing +- Error in callback execution + +**Solutions:** + +```typescript +// Ensure callback is stable +const handleStateChange = useCallback((state) => { + console.log('State changed:', state); +}, []); + +// Wrap in try-catch +const handleStateChange = (state) => { + try { + console.log('State changed:', state); + // Your logic here + } catch (error) { + console.error('Error in state change callback:', error); + } +}; + +// Verify callback is passed + + +// Check if callback is being invoked (add logging in hook) +console.log('Calling onStateChange with:', state); +onStateChange?.(state); +``` + +#### 5. Memory Leak with Worker + +**Symptoms:** +- Browser tab becomes slow over time +- Multiple workers running +- Memory usage increases + +**Possible Causes:** +- Worker not terminated on unmount +- Multiple widget instances +- Worker cleanup not executed + +**Solutions:** + +```typescript +// Verify cleanup on unmount +useEffect(() => { + // ... worker initialization + + return () => { + console.log('Cleaning up worker'); + if (workerRef.current) { + workerRef.current.terminate(); + workerRef.current = null; + } + }; +}, []); + +// Check for multiple widget instances +// Only render one UserState widget at a time + +// Monitor worker instances in DevTools +// Performance > Memory > Take snapshot +``` + +#### 6. Dual Timer Mismatch + +**Symptoms:** +- State timer and idle code timer show different values +- Timers not in sync +- Idle code timer doesn't stop on Available + +**Possible Causes:** +- Timestamps not set correctly +- Worker messages mixed up +- Logic error in timer reset + +**Solutions:** + +```typescript +// Check timestamps +console.log('State timestamp:', store.lastStateChangeTimestamp); +console.log('Idle code timestamp:', store.lastIdleCodeChangeTimestamp); + +// Verify timer values +console.log('Elapsed time:', elapsedTime); +console.log('Idle elapsed time:', lastIdleStateChangeElapsedTime); + +// Check if idle timer should be stopped +if (currentState === 'Available') { + console.log('Idle timer should be stopped'); + // Should show -1 or 0 +} +``` + +--- + +## Related Documentation + +- [Agent Documentation](./agent.md) - Usage examples and props +- [MobX Patterns](../../../../ai-docs/patterns/mobx-patterns.md) - Store patterns +- [React Patterns](../../../../ai-docs/patterns/react-patterns.md) - Component patterns +- [Testing Patterns](../../../../ai-docs/patterns/testing-patterns.md) - Testing guidelines +- [Store Documentation](../../store/ai-docs/agent.md) - Store API reference + +--- + +_Last Updated: 2025-11-26_ +