call-control-sdk 5.2.6 → 5.3.3

package/README.md

@@ -1,218 +1,1179 @@
-### ✨ Call Control SDK [![npm version](https://img.shields.io/npm/v/call-control-sdk.svg?color=blue)](https://www.npmjs.com/package/call-control-sdk) [![npm downloads](https://img.shields.io/npm/dm/call-control-sdk.svg?color=green)](https://www.npmjs.com/package/call-control-sdk)
+# Call Control SDK - Comprehensive Documentation
 
-A lightweight SDK that provides a **draggable call control panel** and utility hooks for managing calls in real-time. Built with **TypeScript**, **Material-UI**, and designed for **agent productivity**.
+## Table of Contents
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Installation & Setup](#installation--setup)
+4. [Core Components](#core-components)
+5. [Hooks & Utilities](#hooks--utilities)
+6. [Services & APIs](#services--apis)
+7. [TypeScript Types](#typescript-types)
+8. [Usage Examples](#usage-examples)
+9. [Best Practices](#best-practices)
+10. [API Reference](#api-reference)
+11. [Troubleshooting](#troubleshooting)
+12. [Productivity Features](#productivity-features)
 
-#### ✨ Features
+---
+
+## Overview
+
+The **Call Control SDK** is a comprehensive TypeScript-based library designed for WebRTC call management in contact center environments. It provides a draggable call control panel with real-time call management capabilities, agent productivity tools, and seamless integration with existing applications.
 
+### Key Features
 - 🎯 **Complete Call Control** – Hold, Mute, Status management, and End Call
 - 🖱️ **Draggable Interface** – Movable panel with persisted position
-- 💾 **State Persistence** – Saves control states in `localStorage`
+- 💾 **State Persistence** – Saves control states in localStorage
 - ⏱️ **Live Call Timer** – Real-time call duration tracking
 - 🎨 **Material-UI Design** – Responsive and accessible UI
 - 📱 **Touch Support** – Works seamlessly on desktop and mobile
 - 🔧 **TypeScript Support** – Full type safety and IntelliSense
 - 🎪 **Singleton State** – Consistent shared state across components
+- 📊 **Event Tracking** – Comprehensive analytics and monitoring
+- 🔄 **WebSocket Integration** – Real-time communication
+- 📞 **Conference Calling** – Multi-line conference management
+- 🔀 **Call Transfer** – Transfer to agents, processes, or queues
+
+---
+
+## Architecture
+
+### Core Architecture Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Call Control SDK                         │
+├─────────────────────────────────────────────────────────────┤
+│  Components Layer                                           │
+│  ├── CallControlPanel (Main UI Component)                  │
+│  ├── CallControls (Control Buttons & Logic)                │
+│  ├── Dialog Components (Transfer, Conference, etc.)         │
+│  └── SDKProvider (Context Provider)                        │
+├─────────────────────────────────────────────────────────────┤
+│  Hooks Layer                                                │
+│  ├── useSDKState (State Management)                        │
+│  ├── useClickToCall (Call Initiation)                      │
+│  ├── useEndCall (Call Termination)                         │
+│  ├── useLogout (Agent Logout)                              │
+│  ├── useDraggable (Drag & Drop)                            │
+│  └── eventsTracker (Analytics)                             │
+├─────────────────────────────────────────────────────────────┤
+│  Services Layer                                             │
+│  ├── axios.ts (HTTP Client)                                │
+│  ├── request.ts (API Hooks)                                │
+│  ├── endPoint.ts (API Endpoints)                           │
+│  └── websocketClient.ts (Real-time Communication)          │
+├─────────────────────────────────────────────────────────────┤
+│  State Management                                           │
+│  ├── sdk-state.ts (Singleton State Manager)                │
+│  └── types.ts (TypeScript Definitions)                     │
+└─────────────────────────────────────────────────────────────┘
+```
 
-[![bundle size](https://img.shields.io/bundlephobia/minzip/call-control-sdk?color=orange&fontSize=12px)](https://bundlephobia.com/package/call-control-sdk)
+### State Management Flow
 
-##### 📦 Installation
+```mermaid
+graph TD
+    A[SDK Initialization] --> B[State Manager]
+    B --> C[localStorage Persistence]
+    B --> D[Component Updates]
+    D --> E[UI Rendering]
+    E --> F[User Interactions]
+    F --> G[API Calls]
+    G --> H[State Updates]
+    H --> B
+    
+    I[WebSocket Events] --> J[Real-time Updates]
+    J --> B
+    
+    K[Event Tracking] --> L[Analytics]
+    L --> M[Performance Monitoring]
+```
+
+---
+
+## Installation & Setup
+
+### Prerequisites
+- Node.js 16+ 
+- React 16+
+- TypeScript 5+
+
+### Installation
 
 ```bash
 npm install call-control-sdk
 ```
 
-###### 🔑 Peer Dependencies
+### Peer Dependencies
 
 ```bash
 npm install react react-dom axios @mui/material @mui/icons-material @emotion/react @emotion/styled
 ```
 
-##### 📚 Table of Contents
+### Basic Setup
+
+```tsx
+import React, { useEffect } from 'react';
+import { initSDK, CallControlPanel } from 'call-control-sdk';
+
+function App() {
+  useEffect(() => {
+    // Initialize the SDK
+    initSDK({
+      apiKey: "your-api-key",
+      tenantId: "your-tenant-id", 
+      agentId: "your-agent-id"
+    });
+  }, []);
+
+  return (
+    <div className="app">
+      <h1>Agent Dashboard</h1>
+      <CallControlPanel 
+        onDataChange={(data) => {
+          console.log('Call data updated:', data);
+        }}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+---
+
+## Core Components
+
+### 1. CallControlPanel
+
+The main UI component that renders the draggable call control interface.
+
+```tsx
+interface CallControlPanelProps {
+  onDataChange?: (data: CallData) => void;
+}
+
+// Usage
+<CallControlPanel 
+  onDataChange={(callData) => {
+    // Handle call data changes
+    updateDashboard(callData);
+  }}
+/>
+```
+
+**Features:**
+- Draggable positioning with persistence
+- Real-time call status display
+- Agent status management
+- Call duration timer
+- Control buttons (Hold, Mute, Transfer, Conference, End Call)
+
+### 2. CallControls
+
+The core control component containing all call management buttons and logic.
+
+**Key Controls:**
+- **Agent Ready**: Set agent status to ready
+- **Hold/Resume**: Toggle call hold state
+- **Mute/Unmute**: Toggle microphone state
+- **Transfer**: Transfer call to another agent/queue/process
+- **Conference**: Add participants to conference call
+- **End Call**: Terminate call with disposition
+
+### 3. Dialog Components
+
+#### ConferenceDialog
+Manages multi-line conference calls with up to 5 lines.
+
+```tsx
+// Conference line management
+interface ConferenceLineTypes {
+  line: number;
+  status: string;
+  type: "external" | "internal" | "";
+  phone: string;
+  isMute: boolean;
+  isHold: boolean;
+  isCallStart: boolean;
+  isMergeCall: boolean;
+}
+```
+
+#### CallTransferDialog
+Handles call transfers to:
+- **Agents**: Transfer to specific agents
+- **Processes**: Transfer to business processes
+- **Queues**: Transfer to call queues
+
+#### EndCallDispositionDialog
+Captures call disposition and follow-up information:
+- Disposition codes (Resolved, Not Interested)
+- Follow-up requirements
+- Callback scheduling
+
+---
+
+## Hooks & Utilities
+
+### 1. useSDKState
+
+Provides reactive access to the SDK's global state.
+
+```tsx
+import { useSDKState } from 'call-control-sdk';
+
+function MyComponent() {
+  const state = useSDKState();
+  
+  return (
+    <div>
+      <p>Agent Status: {state.status}</p>
+      <p>Call Duration: {state.callStartTime}</p>
+      <p>Is Muted: {state.isMuted ? 'Yes' : 'No'}</p>
+    </div>
+  );
+}
+```
+
+### 2. useClickToCall
+
+Initiates outbound calls to phone numbers.
+
+```tsx
+import { useClickToCall } from 'call-control-sdk';
+
+function DialerComponent() {
+  const { handleStartCall, isLoading, isSuccess, error } = useClickToCall();
+  
+  const makeCall = () => {
+    handleStartCall({ mobileNumber: "1234567890" });
+  };
+  
+  return (
+    <button onClick={makeCall} disabled={isLoading}>
+      {isLoading ? 'Calling...' : 'Call'}
+    </button>
+  );
+}
+```
+
+### 3. useEndCall
+
+Terminates active calls with disposition tracking.
+
+```tsx
+import { useEndCall } from 'call-control-sdk';
+
+function EndCallComponent() {
+  const { handleEndCall, isLoading } = useEndCall();
+  
+  const endCall = () => {
+    handleEndCall({
+      disposition: "RES",
+      followUp: "N",
+      callbackDate: "",
+      callbackHrs: "",
+      callbackMins: ""
+    });
+  };
+  
+  return (
+    <button onClick={endCall} disabled={isLoading}>
+      End Call
+    </button>
+  );
+}
+```
+
+### 4. useLogout
+
+Handles agent logout functionality.
+
+```tsx
+import { useLogout } from 'call-control-sdk';
+
+function LogoutComponent() {
+  const { logout, isLoading } = useLogout();
+  
+  return (
+    <button onClick={logout} disabled={isLoading}>
+      {isLoading ? 'Logging out...' : 'Logout'}
+    </button>
+  );
+}
+```
+
+### 5. useDraggable
+
+Provides drag-and-drop functionality for UI elements.
+
+```tsx
+import { useDraggable } from 'call-control-sdk';
+
+function DraggablePanel() {
+  const { position, isDragging, dragRef, handleMouseDown, handleTouchStart } = 
+    useDraggable({ x: 100, y: 100 }, (newPosition) => {
+      console.log('Moved to:', newPosition);
+    });
+  
+  return (
+    <div
+      ref={dragRef}
+      onMouseDown={handleMouseDown}
+      onTouchStart={handleTouchStart}
+      style={{
+        position: 'fixed',
+        left: position.x,
+        top: position.y,
+        cursor: isDragging ? 'grabbing' : 'grab'
+      }}
+    >
+      Drag me
+    </div>
+  );
+}
+```
+
+---
+
+## Services & APIs
+
+### 1. HTTP Client (axios.ts)
+
+Configured Axios instance with:
+- Base URL configuration
+- Authorization headers
+- Request/response interceptors
+- Error handling
+- Retry logic for 401 errors
+
+```tsx
+// Automatic token injection
+axiosInstance.interceptors.request.use((config) => {
+  const token = getAuthToken();
+  if (token && config.headers) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+```
+
+### 2. API Request Hooks (request.ts)
+
+Custom hooks for different HTTP methods:
+
+#### useGetRequest
+```tsx
+const [getData, { isLoading, isSuccess, error, data }] = useGetRequest<User>({
+  onSuccess: (response) => console.log('Success:', response),
+  onError: (error) => console.error('Error:', error)
+});
+
+// Usage
+getData('/api/users');
+```
+
+#### usePostRequest
+```tsx
+const [createUser, { isLoading, isSuccess, error }] = usePostRequest<User>({
+  onSuccess: (response) => console.log('User created:', response)
+});
+
+// Usage
+createUser('/api/users', userData);
+```
+
+### 3. API Endpoints (endPoint.ts)
+
+Centralized endpoint configuration:
+
+```tsx
+export const END_POINT = {
+  LOGIN: `${BASE_URL}/api/v1/cti/login?provider=convox`,
+  READY_AGENT: `${BASE_URL}/api/v1/cti/ready-agent?provider=convox`,
+  CLICK_TO_CALL: `${BASE_URL}/api/v1/cti/calls?provider=convox`,
+  HOLD_CALL: `${BASE_URL}/api/v1/cti/calls/hold?provider=convox`,
+  MUTE_CALL: `${BASE_URL}/api/v1/cti/calls/mute?provider=convox`,
+  END_CALL: `${BASE_URL}/api/v1/cti/calls/end?provider=convox`,
+  CONFERENCE_CALL: `${BASE_URL}/api/v1/cti/calls/conference?provider=convox`,
+  TRANSFER_CALL: `${BASE_URL}/api/v1/cti/calls/transfer?provider=convox`,
+  // ... more endpoints
+};
+```
+
+### 4. WebSocket Integration
+
+Real-time communication for call events:
+
+```tsx
+// WebSocket connection setup
+useEffect(() => {
+  if (state.agentId) {
+    const ws = new WebSocket(`${WS_END_POINT.WS}?agent_id=${state.agentId}`);
+    
+    ws.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+      sdkStateManager.updateCallData(data);
+      
+      if (data.status === "ONCALL") {
+        sdkStateManager.startCall();
+      }
+      if (data.status === "WRAPUP") {
+        sdkStateManager.endCall();
+      }
+    };
+    
+    return () => ws.close();
+  }
+}, [state.agentId]);
+```
+
+---
+
+## TypeScript Types
+
+### Core Types
+
+```tsx
+// Call data structure
+interface CallData {
+  mobileNumber?: string;
+  callReferenceId?: string;
+  convoxId?: string;
+  type?: string;
+  status?: string;
+  agent_id?: string;
+  phone_number?: string;
+  event_time?: string;
+  convox_id?: string;
+  process_id?: string;
+  process_name?: string;
+}
+
+// Agent status types
+type CallStatus = 
+  | "idle"
+  | "ready" 
+  | "break"
+  | "on call"
+  | "wrap up"
+  | "dial"
+  | "hold"
+  | "mute";
+
+// Conference line configuration
+type ConferenceLineTypes = {
+  line: number;
+  status: string;
+  type: "external" | "internal" | "";
+  phone: string;
+  isMute: boolean;
+  isHold: boolean;
+  isCallStart: boolean;
+  isMergeCall: boolean;
+};
+
+// SDK state interface
+interface SDKState {
+  apiKey: string | null;
+  process?: { process_id: number; process_name: string } | null;
+  agentId: string;
+  isInitialized: boolean;
+  isHolding: boolean;
+  isMuted: boolean;
+  status: CallStatus;
+  convox_id?: string;
+  process_id?: number;
+  callStartTime: number | null;
+  position?: { x: number; y: number };
+  controlPanelPosition: { x: number; y: number };
+  iframePosition: { x: number; y: number };
+  callData: CallData;
+  conferenceLine: ConferenceLineTypes[];
+}
+```
+
+### API Request Types
+
+```tsx
+// Request result interface
+interface RequestResult<T> {
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+  error: AxiosError | null;
+  data: AxiosResponse<T> | null;
+}
+
+// Request options
+interface RequestOptions {
+  onSuccess?: (response: AxiosResponse, request: any) => void;
+  onError?: (error: any, request: any) => void;
+}
+
+// Hook signatures
+type UseGetRequest<T = UseApiRequest> = [
+  (url: string, config?: AxiosRequestConfig) => void,
+  RequestResult<T>
+];
+
+type UsePostRequest<T = UseApiRequest> = [
+  (url: string, payload: T, config?: AxiosRequestConfig) => void,
+  RequestResult<T>
+];
+```
+
+---
+
+## Usage Examples
+
+### 1. Complete Agent Dashboard
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { 
+  initSDK, 
+  CallControlPanel, 
+  useClickToCall, 
+  useEndCall, 
+  useLogout 
+} from 'call-control-sdk';
+
+function AgentDashboard() {
+  const [callData, setCallData] = useState(null);
+  
+  // Initialize SDK
+  useEffect(() => {
+    initSDK({
+      apiKey: process.env.REACT_APP_API_KEY,
+      tenantId: process.env.REACT_APP_TENANT_ID,
+      agentId: process.env.REACT_APP_AGENT_ID
+    });
+  }, []);
 
-1. [Getting Started](#-getting-started)
-2. [Core API](#-core-api)
-   - [initSDK](#initsdk)
-   - [CallControlPanel](#callcontrolpanel)
-   - [updateCallData](#updatecalldata)
-3. [Hooks](#-hooks)
-   - [useLogout](#uselogout)
-   - [useEndCall](#useendcall)
-4. [Payloads](#-payloads)
-5. [Control Features](#-control-features)
-6. [Browser Support](#-browser-support)
-7. [License](#-license)
+  // Call management hooks
+  const { handleStartCall, isLoading: calling } = useClickToCall();
+  const { handleEndCall, isLoading: ending } = useEndCall();
+  const { logout, isLoading: loggingOut } = useLogout();
+
+  const handleCallDataChange = (data) => {
+    setCallData(data);
+    // Update dashboard metrics
+    updateDashboardMetrics(data);
+  };
 
-##### 🚀 Getting Started
+  return (
+    <div className="agent-dashboard">
+      <header className="dashboard-header">
+        <h1>Agent Dashboard</h1>
+        <button onClick={logout} disabled={loggingOut}>
+          {loggingOut ? 'Logging out...' : 'Logout'}
+        </button>
+      </header>
+      
+      <main className="dashboard-content">
+        <div className="call-controls">
+          <CallControlPanel onDataChange={handleCallDataChange} />
+        </div>
+        
+        <div className="dashboard-widgets">
+          <CallMetricsWidget data={callData} />
+          <CustomerInfoWidget data={callData} />
+          <CallHistoryWidget />
+        </div>
+      </main>
+    </div>
+  );
+}
+```
 
-### 1. Initialize the SDK
+### 2. Custom Call Controls
 
 ```tsx
-import { useEffect } from "react";
-import { initSDK } from "call-control-sdk";
+import React from 'react';
+import { useSDKState, useClickToCall, useEndCall } from 'call-control-sdk';
+
+function CustomCallControls() {
+  const state = useSDKState();
+  const { handleStartCall } = useClickToCall();
+  const { handleEndCall } = useEndCall();
+
+  const isOnCall = state.callData?.status === "ONCALL";
+  const callDuration = state.callStartTime 
+    ? Math.floor((Date.now() - state.callStartTime) / 1000)
+    : 0;
+
+  const formatDuration = (seconds) => {
+    const mins = Math.floor(seconds / 60);
+    const secs = seconds % 60;
+    return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+  };
+
+  return (
+    <div className="custom-controls">
+      <div className="call-status">
+        <span className="status">{state.status}</span>
+        {isOnCall && (
+          <span className="duration">{formatDuration(callDuration)}</span>
+        )}
+      </div>
+      
+      <div className="control-buttons">
+        {!isOnCall && (
+          <button onClick={() => handleStartCall({ mobileNumber: "1234567890" })}>
+            Start Call
+          </button>
+        )}
+        
+        {isOnCall && (
+          <>
+            <button 
+              onClick={() => handleEndCall({ disposition: "RES" })}
+              className="end-call"
+            >
+              End Call
+            </button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### 3. Conference Call Management
+
+```tsx
+import React, { useState } from 'react';
+import { useSDKState } from 'call-control-sdk';
+
+function ConferenceManager() {
+  const state = useSDKState();
+  const [showConference, setShowConference] = useState(false);
+
+  const addParticipant = (phoneNumber) => {
+    // Find available conference line
+    const availableLine = state.conferenceLine.find(
+      line => line.line !== 1 && line.status === "IDLE"
+    );
+    
+    if (availableLine) {
+      // Initiate conference call
+      handleConferenceCall(availableLine.line, phoneNumber);
+    }
+  };
+
+  return (
+    <div className="conference-manager">
+      <button onClick={() => setShowConference(true)}>
+        Manage Conference
+      </button>
+      
+      {showConference && (
+        <div className="conference-dialog">
+          <h3>Conference Lines</h3>
+          {state.conferenceLine.map(line => (
+            <div key={line.line} className="conference-line">
+              <span>Line {line.line}: {line.status}</span>
+              {line.line !== 1 && (
+                <input 
+                  placeholder="Phone number"
+                  onBlur={(e) => addParticipant(e.target.value)}
+                />
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
 
-// Initialize at the top level of your app
+---
+
+## Best Practices
+
+### 1. Initialization
+
+```tsx
+// ✅ Good: Initialize SDK early in app lifecycle
 function App() {
   useEffect(() => {
-    // Initialize the SDK.
     try {
       initSDK({
-        apiKey: "your-api-key",
-        tenantId: "your-tenant-id",
-        agentId: "your-agent-id",
+        apiKey: process.env.REACT_APP_API_KEY,
+        tenantId: process.env.REACT_APP_TENANT_ID,
+        agentId: process.env.REACT_APP_AGENT_ID
       });
-      console.log("SDK initialized successfully");
     } catch (error) {
-      console.error("SDK initialization failed:", error);
+      console.error('SDK initialization failed:', error);
+      // Handle initialization error
     }
   }, []);
 
-  return <h1>My App</h1>;
+  return <YourApp />;
+}
+
+// ❌ Bad: Initializing in component that might unmount
+function SomeComponent() {
+  useEffect(() => {
+    initSDK(config); // This might be called multiple times
+  }, []);
 }
 ```
 
-### 2. Add the Call Control Panel
+### 2. State Management
 
 ```tsx
-import { CallControlPanel } from "call-control-sdk";
-
-export default function App() {
-  const handleDataChange = (data) => {
-    console.log("Call data updated:", data);
-  };
-
+// ✅ Good: Use the provided state hook
+function MyComponent() {
+  const state = useSDKState();
+  
   return (
     <div>
-      <h1>Agent Dashboard</h1>
-      <CallControlPanel onDataChange={handleDataChange} />
+      <p>Status: {state.status}</p>
+      <p>Call Duration: {state.callStartTime}</p>
     </div>
   );
 }
+
+// ❌ Bad: Direct state access
+function MyComponent() {
+  const state = sdkStateManager.getState(); // Won't trigger re-renders
+  return <div>{state.status}</div>;
+}
 ```
 
-### 3. Logout Agent
+### 3. Error Handling
 
 ```tsx
-import { useLogout } from "call-control-sdk";
+// ✅ Good: Comprehensive error handling
+function CallComponent() {
+  const { handleStartCall, isLoading, isError, error } = useClickToCall();
+  
+  const makeCall = async () => {
+    try {
+      await handleStartCall({ mobileNumber: "1234567890" });
+    } catch (error) {
+      console.error('Call failed:', error);
+      // Show user-friendly error message
+      showNotification('Call failed. Please try again.');
+    }
+  };
 
-export default function LogoutButton() {
-  const { logout, isLoading, isSuccess, isError, error } = useLogout();
-  return <button onClick={logout}>Logout</button>;
+  return (
+    <div>
+      <button onClick={makeCall} disabled={isLoading}>
+        {isLoading ? 'Calling...' : 'Call'}
+      </button>
+      {isError && <p className="error">Error: {error?.message}</p>}
+    </div>
+  );
 }
 ```
 
-### 4. End Call
+### 4. Performance Optimization
 
 ```tsx
-import { useEndCall } from "call-control-sdk";
+// ✅ Good: Memoize expensive operations
+function CallMetrics({ callData }) {
+  const formattedDuration = useMemo(() => {
+    if (!callData?.startTime) return '00:00';
+    const duration = Date.now() - callData.startTime;
+    return formatDuration(duration);
+  }, [callData?.startTime]);
 
-export default function EndCallButton() {
-  const { handleEndCall, isLoading, isSuccess, isError, error } = useEndCall();
+  return <div>Duration: {formattedDuration}</div>;
+}
 
-  const onEndCall = () => {
-    handleEndCall({
-      disposition: "RES", // Call disposition
-    });
-  };
+// ✅ Good: Debounce user input
+function PhoneInput() {
+  const [phoneNumber, setPhoneNumber] = useState('');
+  const debouncedPhone = useDebounce(phoneNumber, 500);
+  
+  useEffect(() => {
+    if (debouncedPhone.length === 10) {
+      validatePhoneNumber(debouncedPhone);
+    }
+  }, [debouncedPhone]);
+}
+```
 
+### 5. Accessibility
+
+```tsx
+// ✅ Good: Accessible controls
+function AccessibleCallControls() {
+  const state = useSDKState();
+  
   return (
-    <div>
-      <button onClick={onEndCall} disabled={isLoading}>
-        {isLoading ? "Ending Call..." : "End Call"}
+    <div role="toolbar" aria-label="Call controls">
+      <button
+        onClick={handleMute}
+        aria-pressed={state.isMuted}
+        aria-label={state.isMuted ? 'Unmute microphone' : 'Mute microphone'}
+      >
+        {state.isMuted ? <MicOffIcon /> : <MicIcon />}
+      </button>
+      
+      <button
+        onClick={handleHold}
+        aria-pressed={state.isHolding}
+        aria-label={state.isHolding ? 'Resume call' : 'Hold call'}
+      >
+        {state.isHolding ? <PlayIcon /> : <PauseIcon />}
       </button>
-      {isSuccess && <p>✅ Call ended successfully</p>}
-      {isError && <p>❌ Error: {error?.message}</p>}
     </div>
   );
 }
 ```
 
-##### 🛠 Core API
+---
+
+## API Reference
+
+### Core Functions
+
+#### `initSDK(config: InitSDKParams): void`
+
+Initializes the Call Control SDK.
+
+**Parameters:**
+- `config.apiKey` (string, required): API key for authentication
+- `config.tenantId` (string, required): Tenant ID for events/authentication  
+- `config.agentId` (string, required): Agent ID for call controls
+
+**Example:**
+```tsx
+initSDK({
+  apiKey: "your-api-key",
+  tenantId: "tenant-123",
+  agentId: "agent-456"
+});
+```
+
+#### `CallControlPanel`
+
+React component that renders the draggable call control interface.
+
+**Props:**
+- `onDataChange?: (data: CallData) => void`: Callback fired when call data changes
+
+**Example:**
+```tsx
+<CallControlPanel 
+  onDataChange={(data) => {
+    console.log('Call updated:', data);
+  }}
+/>
+```
+
+### Hooks
 
-### `initSDK(config)`
+#### `useSDKState(): SDKState`
 
-Initializes the SDK. Must be called **before using any components or hooks**.
+Returns the current SDK state with reactive updates.
 
-**Parameters**:
+**Returns:** `SDKState` object containing:
+- `isInitialized`: boolean
+- `status`: CallStatus
+- `isHolding`: boolean
+- `isMuted`: boolean
+- `callData`: CallData
+- `conferenceLine`: ConferenceLineTypes[]
+- And more...
 
-| Name       | Type   | Required | Description                         |
-| ---------- | ------ | -------- | ----------------------------------- |
-| `apiKey`   | string | ✅       | API key for authentication          |
-| `tenantId` | string | ✅       | Tenant ID for events/authentication |
-| `agentId`  | string | ✅       | Agent ID for call controls          |
+#### `useClickToCall()`
 
-### `CallControlPanel`
+Hook for initiating outbound calls.
 
-Draggable control panel for call management.
+**Returns:**
+- `handleStartCall`: (payload: StartCallPayload) => Promise<void>
+- `isLoading`: boolean
+- `isSuccess`: boolean
+- `isError`: boolean
+- `error`: any
+- `data`: any
 
-**Props**:
+#### `useEndCall()`
 
-| Prop            | Type     | Required | Description                                                                                        |
-| --------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- |
-| `onDataChange?` | function | ❌       | Callback fired when call data changes. Receives `{ mobileNumber, callReferenceId, agentLoginId }`. |
+Hook for ending active calls.
 
-### `updateCallData(data: Partial<CallData>)`
+**Returns:**
+- `handleEndCall`: (data: EndCallData) => Promise<void>
+- `isLoading`: boolean
+- `isSuccess`: boolean
+- `isError`: boolean
+- `error`: any
+- `data`: any
 
-Update call data programmatically.
+#### `useLogout()`
 
-**Parameters**:
+Hook for agent logout functionality.
 
-| Field              | Type   | Description            |
-| ------------------ | ------ | ---------------------- |
-| `mobileNumber?`    | string | Mobile phone number    |
-| `callReferenceId?` | string | Unique call reference  |
-| `agentLoginId?`    | string | Agent login identifier |
+**Returns:**
+- `logout`: () => Promise<void>
+- `isLoading`: boolean
+- `isSuccess`: boolean
+- `isError`: boolean
+- `error`: any
+- `data`: any
+
+---
 
-##### 🪝 Hooks
+## Troubleshooting
 
-### `useLogout()`
+### Common Issues
 
-Logs out the current agent.
+#### 1. SDK Not Initializing
 
+**Problem:** SDK fails to initialize
+**Solution:**
 ```tsx
-const { logOut } = useLogout();
-<button onClick={logOut}>Logout</button>;
+// Check if all required parameters are provided
+try {
+  initSDK({
+    apiKey: "valid-api-key", // Ensure this is not empty
+    tenantId: "valid-tenant-id", // Ensure this is not empty
+    agentId: "valid-agent-id" // Ensure this is not empty
+  });
+} catch (error) {
+  console.error('SDK initialization failed:', error);
+}
 ```
 
-### `useEndCall()`
+#### 2. State Not Updating
 
-Hook for ending an active call.
+**Problem:** Components not re-rendering when state changes
+**Solution:**
+```tsx
+// ✅ Use the hook, not direct state access
+function MyComponent() {
+  const state = useSDKState(); // This will trigger re-renders
+  
+  // ❌ Don't do this
+  // const state = sdkStateManager.getState();
+}
+```
 
-**Returns**:
+#### 3. WebSocket Connection Issues
 
-| Key             | Type     | Description                                                     |
-| --------------- | -------- | --------------------------------------------------------------- |
-| `handleEndCall` | function | `(payload: EndCallPayload) => void` – triggers end-call request |
-| `isLoading`     | boolean  | True while request is pending                                   |
-| `isSuccess`     | boolean  | True if request succeeded                                       |
-| `isError`       | boolean  | True if request failed                                          |
-| `error`         | any      | Error object if failed                                          |
-| `data`          | any      | API response on success                                         |
+**Problem:** Real-time updates not working
+**Solution:**
+```tsx
+// Check WebSocket connection
+useEffect(() => {
+  if (state.agentId) {
+    const ws = new WebSocket(`${WS_END_POINT.WS}?agent_id=${state.agentId}`);
+    
+    ws.onopen = () => console.log('WebSocket connected');
+    ws.onerror = (error) => console.error('WebSocket error:', error);
+    ws.onclose = () => console.log('WebSocket disconnected');
+    
+    return () => ws.close();
+  }
+}, [state.agentId]);
+```
 
-##### 📦 Payloads
+#### 4. Call Controls Not Working
 
-### `EndCallPayload`
+**Problem:** Buttons not responding or API calls failing
+**Solution:**
+```tsx
+// Check agent status and call state
+function CallControls() {
+  const state = useSDKState();
+  
+  // Ensure agent is ready before allowing calls
+  const canMakeCall = state.status === "idle" || state.status === "ready";
+  
+  return (
+    <button 
+      onClick={handleCall}
+      disabled={!canMakeCall || isLoading}
+    >
+      Call
+    </button>
+  );
+}
+```
+
+### Debug Mode
+
+Enable debug logging:
 
-```ts
-interface EndCallPayload {
-  disposition?: string; // Call disposition (default: "RES")
+```tsx
+// Add to your app initialization
+if (process.env.NODE_ENV === 'development') {
+  // Enable SDK debug mode
+  sdkStateManager.debugStorage();
+  
+  // Log all state changes
+  sdkStateManager.subscribe(() => {
+    console.log('SDK State changed:', sdkStateManager.getState());
+  });
 }
 ```
 
-## 🎛 Control Features
+---
 
-- **Status Management**: Idle / Break
-- **Call Controls**: Hold / Resume, Mute / Unmute, End Call, Agent Status
-- **Persistent State**: Hold, mute, agent status, panel position, call timer
+## Productivity Features
 
-##### 🌍 Browser Support
+### 1. Agent Productivity Metrics
 
-- ✅ Chrome 60+
-- ✅ Firefox 60+
-- ✅ Safari 12+
-- ✅ Edge 79+
+The SDK automatically tracks various productivity metrics:
+
+```tsx
+// Event tracking for productivity analysis
+eventTracker.logEvent('callStarted', {
+  agentId: state.agentId,
+  phoneNumber: state.callData.phone_number,
+  timestamp: new Date().toISOString(),
+  processId: state.process?.process_id
+});
+
+eventTracker.logEvent('callEnded', {
+  agentId: state.agentId,
+  duration: callDuration,
+  disposition: disposition,
+  timestamp: new Date().toISOString()
+});
+```
+
+### 2. Real-time Status Updates
+
+```tsx
+// Automatic status synchronization
+useEffect(() => {
+  const ws = new WebSocket(`${WS_END_POINT.WS}?agent_id=${state.agentId}`);
+  
+  ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    
+    // Update call data
+    sdkStateManager.updateCallData(data);
+    
+    // Track status changes
+    eventTracker.logEvent('statusChanged', {
+      from: state.status,
+      to: data.status,
+      timestamp: new Date().toISOString()
+    });
+  };
+}, [state.agentId]);
+```
+
+### 3. Call Quality Monitoring
+
+```tsx
+// Monitor call quality metrics
+function CallQualityMonitor() {
+  const state = useSDKState();
+  
+  useEffect(() => {
+    if (state.callData?.status === "ONCALL") {
+      const startTime = Date.now();
+      
+      const interval = setInterval(() => {
+        const duration = Date.now() - startTime;
+        
+        // Log call quality metrics every 30 seconds
+        if (duration % 30000 === 0) {
+          eventTracker.logEvent('callQualityMetrics', {
+            duration: duration,
+            isHolding: state.isHolding,
+            isMuted: state.isMuted,
+            timestamp: new Date().toISOString()
+          });
+        }
+      }, 1000);
+      
+      return () => clearInterval(interval);
+    }
+  }, [state.callData?.status, state.isHolding, state.isMuted]);
+}
+```
+
+### 4. Performance Analytics
+
+```tsx
+// Track UI performance
+function PerformanceTracker() {
+  useEffect(() => {
+    // Track component render times
+    const startTime = performance.now();
+    
+    return () => {
+      const renderTime = performance.now() - startTime;
+      eventTracker.logEvent('componentRender', {
+        component: 'CallControlPanel',
+        renderTime: renderTime,
+        timestamp: new Date().toISOString()
+      });
+    };
+  }, []);
+}
+```
+
+### 5. User Experience Optimization
+
+```tsx
+// Optimize user interactions
+function OptimizedCallControls() {
+  const state = useSDKState();
+  
+  // Debounce rapid button clicks
+  const debouncedHold = useDebounce(() => {
+    handleHoldToggle();
+  }, 300);
+  
+  // Track user interaction patterns
+  const trackInteraction = (action) => {
+    eventTracker.logEvent('userInteraction', {
+      action: action,
+      agentId: state.agentId,
+      timestamp: new Date().toISOString()
+    });
+  };
+  
+  return (
+    <div>
+      <button 
+        onClick={() => {
+          trackInteraction('holdToggle');
+          debouncedHold();
+        }}
+      >
+        Hold
+      </button>
+    </div>
+  );
+}
+```
 
 ---
 
-##### 📄 License
+## Conclusion
+
+The Call Control SDK provides a comprehensive solution for WebRTC call management in contact center environments. With its draggable interface, real-time state management, extensive TypeScript support, and productivity features, it enables developers to build robust call center applications quickly and efficiently.
+
+Key benefits:
+- **Rapid Development**: Pre-built components and hooks accelerate development
+- **Type Safety**: Full TypeScript support prevents runtime errors
+- **Real-time Updates**: WebSocket integration ensures live data synchronization
+- **Productivity Focus**: Built-in analytics and monitoring capabilities
+- **Accessibility**: Material-UI components with proper ARIA support
+- **Mobile Ready**: Touch support and responsive design
+- **Extensible**: Modular architecture allows for easy customization
+
+For additional support or feature requests, please refer to the official documentation or contact the development team.
+
+---
 
-MIT © 2025 [![license](https://img.shields.io/npm/l/call-control-sdk.svg)](#-license)
+*Documentation Version: 1.0*  
+*Last Updated: 2025*  
+*SDK Version: 5.3.0*