call-control-sdk 5.4.8 → 6.0.3

package/dist/index.d.mts

@@ -1,11 +1,75 @@
 import { SxProps } from '@mui/material';
-import { AxiosResponse, AxiosError, AxiosRequestConfig } from 'axios';
 import * as react from 'react';
 
 /**
- * Custom hook for handling agent logout functionality
- * @param options - Optional callbacks for success, error, and completion
- * @returns Object containing logout function and loading state
+ * 🚪 Logout Custom Hook
+ *
+ * @function useLogout
+ * @description 🎯 Custom React hook that provides comprehensive agent logout functionality
+ *              for the CTI SDK. It handles secure logout procedures, complete state cleanup,
+ *              and storage management with intelligent error handling and proper cleanup.
+ *
+ * @returns {Object} Hook return object containing:
+ *   - `logout: () => Promise<any>` - 🚪 Logout function
+ *   - `isLoading: boolean` - ⏳ Loading state indicator
+ *   - `isSuccess: boolean` - ✅ Success state indicator
+ *   - `isError: boolean` - ❌ Error state indicator
+ *   - `error: any` - 🛡️ Error object when logout fails
+ *   - `data: any` - 📊 Response data from successful logout
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in a component
+ * const LogoutButton = () => {
+ *   const {
+ *     logout,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = useLogout();
+ *
+ *   const handleLogout = async () => {
+ *     try {
+ *       const result = await logout();
+ *       console.log('🚪 Logout successful:', result);
+ *       // Redirect to login page or handle success
+ *     } catch (err) {
+ *       console.error('❌ Logout failed:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button
+ *       onClick={handleLogout}
+ *       disabled={isLoading}
+ *     >
+ *       {isLoading ? 'Logging out...' : 'Logout'}
+ *     </button>
+ *   );
+ * };
+ * ```
+ *
+ * @features
+ * - 🚪 Secure agent logout with API validation
+ * - 🗑️ Complete state cleanup and reset
+ * - 💾 Storage management (localStorage & sessionStorage)
+ * - ⏳ Comprehensive loading state management
+ * - 🛡️ Robust error handling and recovery
+ * - 📊 Real-time state updates via SDK manager
+ * - 🔄 Automatic storage cleanup
+ *
+ * @logic
+ * - 🔍 Retrieves agent state from localStorage
+ * - 📦 Constructs logout API payload
+ * - 📡 Makes API call to logout agent
+ * - 🗑️ Clears SDK state manager
+ * - 💾 Clears all storage (localStorage & sessionStorage)
+ * - 📊 Handles success/error states
+ * - ⏳ Manages loading states
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
  */
 declare const useLogout: () => {
     logout: () => Promise<any>;
@@ -17,9 +81,75 @@ declare const useLogout: () => {
 };
 
 /**
- * Custom hook for handling end call functionality
- * @param options - Optional callbacks for success, error, and completion
- * @returns Object containing logout function and loading state
+ * 📞 End Call Custom Hook
+ *
+ * @function useEndCall
+ * @description 🎯 Custom React hook that provides comprehensive call termination functionality
+ *              for the CTI SDK. It handles call disposition capture, callback scheduling,
+ *              and proper call cleanup with intelligent state management and error handling.
+ *
+ * @returns {Object} Hook return object containing:
+ *   - `handleEndCall: (data: EndCallData) => Promise<any>` - 📞 Call termination function
+ *   - `isLoading: boolean` - ⏳ Loading state indicator
+ *   - `isSuccess: boolean` - ✅ Success state indicator
+ *   - `isError: boolean` - ❌ Error state indicator
+ *   - `error: any` - 🛡️ Error object when call fails
+ *   - `data: any` - 📊 Response data from successful calls
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in a component
+ * const EndCallButton = () => {
+ *   const {
+ *     handleEndCall,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = useEndCall();
+ *
+ *   const endCall = async () => {
+ *     try {
+ *       const result = await handleEndCall({
+ *         disposition: "RES",
+ *         followUp: "N"
+ *       });
+ *       console.log('📞 Call ended:', result);
+ *     } catch (err) {
+ *       console.error('❌ End call failed:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button
+ *       onClick={endCall}
+ *       disabled={isLoading}
+ *     >
+ *       {isLoading ? 'Ending...' : 'End Call'}
+ *     </button>
+ *   );
+ * };
+ * ```
+ *
+ * @features
+ * - 🎯 Comprehensive call termination with disposition tracking
+ * - 📅 Callback scheduling and follow-up management
+ * - 🔄 Intelligent state cleanup and reset
+ * - ⏳ Comprehensive loading state management
+ * - 🛡️ Robust error handling and recovery
+ * - 📊 Real-time state updates via SDK manager
+ * - 🔄 Automatic call state management
+ *
+ * @logic
+ * - 🔍 Retrieves agent state from localStorage
+ * - 📦 Constructs comprehensive API payload
+ * - 📡 Makes API call to end call
+ * - 🔄 Updates SDK state manager
+ * - 📊 Handles success/error states
+ * - ⏳ Manages loading states
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
  */
 declare const useEndCall: () => {
     handleEndCall: (data: {
@@ -391,370 +521,123 @@ interface SDKState {
     /** Array of conference lines and their states */
     conferenceLine: ConferenceLineTypes[];
 }
+
 /**
- * @interface RequestOptions
- * @description Interface defining optional success and error callback functions for API requests.
- * Provides a standardized way to handle request lifecycle events with proper error handling.
- *
- * @declaration
- * ```typescript
- * interface RequestOptions {
- *   onSuccess?: (response: AxiosResponse, request: any) => void;
- *   onError?: (error: any, request: any) => void;
- * }
- * ```
- *
- * @requiredParams None (all callbacks are optional)
- *
- * @returnType Interface definition
- *
- * @example
- * ```typescript
- * const requestOptions: RequestOptions = {
- *   onSuccess: (response, request) => {
- *     console.log('Request successful:', response.data);
- *     // Handle successful response
- *   },
- *   onError: (error, request) => {
- *     console.error('Request failed:', error.message);
- *     // Handle error
- *   }
- * };
- * ```
- *
- * @return Interface definition for request callback options
- *
- * @conclusion Essential interface for implementing robust error handling and success callbacks in API operations.
+ * @fileoverview 📞 Click-to-Call Hook for CTI SDK
+ *
+ * This file contains the useClickToCall custom hook that provides comprehensive call initiation
+ * functionality for the CTI SDK. It handles both regular calls and conference calls with
+ * intelligent state management and error handling.
+ *
+ * 🎯 Key Features:
+ * - 📱 Regular call initiation for idle agents
+ * - 👥 Conference call initiation for agents on calls
+ * - 🔄 Intelligent state detection and routing
+ * - ⏳ Loading states and error handling
+ * - 📊 Real-time state updates
+ * - 🛡️ Comprehensive error management
+ *
+ * @author CTI SDK Team
+ * @version 5.4.8
+ * @since 1.0.0
  */
-interface RequestOptions {
-    /**
-     * Callback function triggered when the request succeeds.
-     * @param response - The successful Axios response object
-     * @param request - The original request configuration
-     */
-    onSuccess?: (response: AxiosResponse, request: any) => void;
-    /**
-     * Callback function triggered when the request fails.
-     * @param error - The error object containing failure details
-     * @param request - The original request configuration
-     */
-    onError?: (error: any, request: any) => void;
-    disabledSuccessToast?: boolean;
-}
 /**
- * @interface RequestResult
- * @description Interface defining the return type of API hook state management.
- * Provides comprehensive state tracking for HTTP requests including loading, success, error states, and data.
- *
- * @declaration
- * ```typescript
- * interface RequestResult<T> {
- *   isLoading: boolean;
- *   isSuccess: boolean;
- *   isError: boolean;
- *   error: AxiosError | null;
- *   data: AxiosResponse<T> | null;
- * }
- * ```
+ * 📱 Start Call Payload Interface
  *
- * @requiredParams None (interface definition)
+ * @interface StartCallPayload
+ * @description 📊 Defines the structure for call initiation payload data
+ *              Contains the mobile number required to initiate a call
  *
- * @returnType Interface definition
+ * @properties
+ * - `mobileNumber: string` - 📱 The phone number to call (required)
  *
  * @example
  * ```typescript
- * const [makeRequest, requestState] = usePostRequest<User>();
- *
- * // requestState has type RequestResult<User>
- * if (requestState.isLoading) {
- *   return <LoadingSpinner />;
- * }
- *
- * if (requestState.isError) {
- *   return <ErrorMessage error={requestState.error} />;
- * }
- *
- * if (requestState.isSuccess) {
- *   return <UserData user={requestState.data?.data} />;
- * }
- * ```
- *
- * @return Interface definition for request state management
- *
- * @conclusion Essential interface for consistent state management across all API operations.
- */
-interface RequestResult<T> {
-    /** Boolean flag indicating if the request is currently in progress */
-    isLoading: boolean;
-    /** Boolean flag indicating the request completed successfully */
-    isSuccess: boolean;
-    /** Boolean flag indicating an error occurred during the request */
-    isError: boolean;
-    /** Holds the Axios error object if an error occurred, null otherwise */
-    error: AxiosError | null;
-    /** Holds the successful Axios response data, null if no successful request yet */
-    data: AxiosResponse<T> | null;
-}
-/**
- * @interface UseApiRequest
- * @description Generic interface for custom API hooks that perform HTTP operations with comprehensive state tracking.
- * Provides a standardized pattern for API request functions with built-in state management.
- *
- * @declaration
- * ```typescript
- * interface UseApiRequest<T = {}, P = void> {
- *   (url: string, payloadOrConfig?: P, config?: AxiosRequestConfig): void;
- *   state: RequestResult<T>;
- * }
- * ```
- *
- * @requiredParams None (interface definition)
- *
- * @returnType Interface definition
- *
- * @example
- * ```typescript
- * const fetchUser: UseApiRequest<User, { id: number }> = useApi({
- *   onSuccess: (response) => console.log('User fetched:', response.data),
- *   onError: (error) => console.error('Failed to fetch user:', error)
- * });
- *
- * // Usage
- * fetchUser('/api/users', { id: 123 });
+ * // Basic call initiation payload
+ * const callPayload: StartCallPayload = {
+ *   mobileNumber: "1234567890"
+ * };
  *
- * // Access state
- * if (fetchUser.state.isLoading) {
- *   return <LoadingSpinner />;
- * }
+ * // Usage in component
+ * const { handleStartCall } = useClickToCall();
+ * await handleStartCall({ mobileNumber: "9876543210" });
  * ```
  *
- * @return Interface definition for API request hooks
- *
- * @conclusion Provides a consistent pattern for all API operations with built-in state management and error handling.
+ * @since 1.0.0
+ * @author CTI SDK Team
  */
-interface UseApiRequest<T = {}, P = void> {
-    /**
-     * Executes the API request with the provided parameters
-     * @param url - The API endpoint URL
-     * @param payloadOrConfig - Request payload or configuration object
-     * @param config - Additional Axios configuration options
-     */
-    (url: string, payloadOrConfig?: P, config?: AxiosRequestConfig): void;
-    /** Current state of the request including loading, success, error, and data */
-    state: RequestResult<T>;
+interface StartCallPayload {
+    mobileNumber: string;
 }
 /**
- * @type UseGetRequest
- * @description Tuple type for HTTP GET request hooks with comprehensive state management.
- * Provides a clean API for making GET requests with built-in loading, success, and error states.
- *
- * @declaration
- * ```typescript
- * type UseGetRequest<T = {}> = [
- *   (url: string, config?: AxiosRequestConfig) => void,
- *   RequestResult<T>
- * ];
- * ```
- *
- * @requiredParams None (type definition)
- *
- * @returnType Tuple type definition
- *
- * @example
- * ```typescript
- * const [getUser, userState] = useGetRequest<User>();
- *
- * // Execute request
- * getUser("/api/users/123");
- *
- * // Access state
- * if (userState.isLoading) return <LoadingSpinner />;
- * if (userState.isError) return <ErrorMessage error={userState.error} />;
- * if (userState.isSuccess) return <UserProfile user={userState.data?.data} />;
- * ```
- *
- * @return Tuple type: [request function, state object]
- *
- * @conclusion Provides a consistent pattern for GET requests with comprehensive state management.
- */
-type UseGetRequest<T = {}> = [
-    (url: string, config?: AxiosRequestConfig) => void,
-    RequestResult<T>
-];
-/**
- * @type UsePostRequest
- * @description Tuple type for HTTP POST request hooks with typed payload and state management.
- * Ideal for creating new resources with comprehensive error handling and state tracking.
- *
- * @declaration
- * ```typescript
- * type UsePostRequest<T = {}> = [
- *   (url: string, payload: T, config?: AxiosRequestConfig) => void,
- *   RequestResult<T>
- * ];
- * ```
- *
- * @requiredParams None (type definition)
- *
- * @returnType Tuple type definition
- *
- * @example
- * ```typescript
- * const [createUser, createState] = usePostRequest<User>();
- *
- * // Execute request
- * createUser("/api/users", {
- *   name: "John Doe",
- *   email: "john@example.com"
- * });
- *
- * // Access state
- * if (createState.isLoading) return <LoadingSpinner />;
- * if (createState.isSuccess) {
- *   console.log("User created:", createState.data?.data);
- * }
- * ```
- *
- * @return Tuple type: [request function, state object]
- *
- * @conclusion Essential type for POST operations with robust state management and error handling.
- */
-type UsePostRequest<T = {}> = [
-    (url: string, payload: T, config?: AxiosRequestConfig) => void,
-    RequestResult<T>
-];
-/**
- * @type UsePutRequest
- * @description Tuple type for HTTP PUT request hooks with typed payload and comprehensive state tracking.
- * Perfect for updating existing resources with full state management capabilities.
+ * 📞 Click-to-Call Custom Hook
  *
- * @declaration
- * ```typescript
- * type UsePutRequest<T = {}> = [
- *   (url: string, payload: T, config?: AxiosRequestConfig) => void,
- *   RequestResult<T>
- * ];
- * ```
+ * @function useClickToCall
+ * @description 🎯 Custom React hook that provides comprehensive call initiation functionality
+ *              for the CTI SDK. It intelligently handles both regular calls and conference calls
+ *              based on the current agent state, with proper loading states and error handling.
  *
- * @requiredParams None (type definition)
- *
- * @returnType Tuple type definition
+ * @returns {Object} Hook return object containing:
+ *   - `handleStartCall: (data: StartCallPayload) => Promise<any>` - 📞 Call initiation function
+ *   - `isLoading: boolean` - ⏳ Loading state indicator
+ *   - `isSuccess: boolean` - ✅ Success state indicator
+ *   - `isError: boolean` - ❌ Error state indicator
+ *   - `error: any` - 🛡️ Error object when call fails
+ *   - `data: any` - 📊 Response data from successful calls
  *
  * @example
  * ```typescript
- * const [updateUser, updateState] = usePutRequest<User>();
- *
- * // Execute request
- * updateUser("/api/users/123", {
- *   name: "Jane Doe",
- *   email: "jane@example.com"
- * });
- *
- * // Access state
- * if (updateState.isLoading) return <LoadingSpinner />;
- * if (updateState.isSuccess) {
- *   console.log("User updated:", updateState.data?.data);
- * }
- * ```
- *
- * @return Tuple type: [request function, state object]
- *
- * @conclusion Provides consistent pattern for PUT operations with comprehensive state management.
- */
-type UsePutRequest<T = {}> = [
-    (url: string, payload: T, config?: AxiosRequestConfig) => void,
-    RequestResult<T>
-];
-/**
- * @type UseDeleteRequest
- * @description Tuple type for HTTP DELETE request hooks with optional configuration and state management.
- * Provides clean API for resource deletion with comprehensive error handling.
- *
- * @declaration
- * ```typescript
- * type UseDeleteRequest<T = {}> = [
- *   (url: string, config?: AxiosRequestConfig) => void,
- *   RequestResult<T>
- * ];
- * ```
- *
- * @requiredParams None (type definition)
- *
- * @returnType Tuple type definition
- *
- * @example
- * ```typescript
- * const [deleteUser, deleteState] = useDeleteRequest<void>();
- *
- * // Execute request
- * deleteUser("/api/users/123");
- *
- * // Access state
- * if (deleteState.isLoading) return <LoadingSpinner />;
- * if (deleteState.isSuccess) {
- *   console.log("User deleted successfully");
- * }
- * ```
- *
- * @return Tuple type: [request function, state object]
- *
- * @conclusion Essential type for DELETE operations with robust state management.
- */
-type UseDeleteRequest<T = {}> = [
-    (url: string, config?: AxiosRequestConfig) => void,
-    RequestResult<T>
-];
-/**
- * @type UsePatchRequest
- * @description Tuple type for HTTP PATCH request hooks with typed payload and comprehensive state tracking.
- * Ideal for partial updates with built-in state management and error handling.
- *
- * @declaration
- * ```typescript
- * type UsePatchRequest<T = {}> = [
- *   (url: string, payload: T, config?: AxiosRequestConfig) => void,
- *   RequestResult<T>
- * ];
- * ```
- *
- * @requiredParams None (type definition)
- *
- * @returnType Tuple type definition
- *
- * @example
- * ```typescript
- * const [patchUser, patchState] = usePatchRequest<Partial<User>>();
- *
- * // Execute request
- * patchUser("/api/users/123", {
- *   email: "newemail@example.com"
- * });
- *
- * // Access state
- * if (patchState.isLoading) return <LoadingSpinner />;
- * if (patchState.isSuccess) {
- *   console.log("User patched:", patchState.data?.data);
- * }
+ * // Basic usage in a component
+ * const CallButton = () => {
+ *   const {
+ *     handleStartCall,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = useClickToCall();
+ *
+ *   const makeCall = async () => {
+ *     try {
+ *       const result = await handleStartCall({
+ *         mobileNumber: "1234567890"
+ *       });
+ *       console.log('📞 Call initiated:', result);
+ *     } catch (err) {
+ *       console.error('❌ Call failed:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button
+ *       onClick={makeCall}
+ *       disabled={isLoading}
+ *     >
+ *       {isLoading ? 'Calling...' : 'Make Call'}
+ *     </button>
+ *   );
+ * };
  * ```
  *
- * @return Tuple type: [request function, state object]
- *
- * @conclusion Provides consistent pattern for PATCH operations with comprehensive state management.
- */
-type UsePatchRequest<T = {}> = [
-    (url: string, payload: T, config?: AxiosRequestConfig) => void,
-    RequestResult<T>
-];
-
-interface StartCallPayload {
-    mobileNumber: string;
-}
-/**
- * Custom hook for handling end call functionality
- * @param options - Optional callbacks for success, error, and completion
- * @returns Object containing logout function and loading state
- * @example
- * handleStartCall({ mobileNumber: "1111111111" });
+ * @features
+ * - 🎯 Intelligent call routing based on agent state
+ * - 📱 Regular call initiation for idle agents
+ * - 👥 Conference call initiation for busy agents
+ * - ⏳ Comprehensive loading state management
+ * - 🛡️ Robust error handling and recovery
+ * - 📊 Real-time state updates via SDK manager
+ * - 🔄 Automatic conference dialog management
+ *
+ * @logic
+ * - 🔍 Checks agent status from localStorage state
+ * - 📞 Initiates regular call if agent is IDLE
+ * - 👥 Initiates conference call if agent is ONCALL
+ * - ⚠️ Shows alert if agent is not ready
+ * - 🔄 Updates conference line state for conference calls
+ * - 🎭 Opens conference dialog for conference calls
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
  */
 declare const useClickToCall: () => {
     handleStartCall: (data: StartCallPayload) => Promise<any>;
@@ -959,4 +842,4 @@ declare function getSDKVersion(): string;
  */
 declare function isSDKInitialized(): boolean;
 
-export { CallControlPanel, type CallControlPanelProps, type CallData, type CallStatus, type ConferenceLineTypes, type RequestOptions, type RequestResult, type SDKConfig, type SDKState, type UseApiRequest, type UseDeleteRequest, type UseGetRequest, type UsePatchRequest, type UsePostRequest, type UsePutRequest, getSDKVersion, initSDK, isSDKInitialized, useClickToCall, useEndCall, useLogout };
+export { CallControlPanel, type CallControlPanelProps, type CallData, type CallStatus, type ConferenceLineTypes, type SDKConfig, type SDKState, getSDKVersion, initSDK, isSDKInitialized, useClickToCall, useEndCall, useLogout };