call-control-sdk 6.1.2 → 6.2.0

package/dist/index.d.mts

@@ -258,63 +258,1393 @@ interface CallControlPanelProps {
 // =============================================================================
 
 /**
- * 🚪 Logout Hook
+ * @fileoverview 📞 TypeScript Declaration File for useEndCall Hook
  *
- * @function useLogout
- * @description Custom hook for handling agent logout functionality.
- * Provides logout functionality with proper cleanup and state management.
+ * This file contains TypeScript type definitions for the useEndCall custom hook
+ * and its related interfaces. It provides comprehensive type safety and IntelliSense
+ * support for developers using the CTI SDK call termination functionality.
+ *
+ * 🎯 Key Type Definitions:
+ * - 📞 EndCallPayload interface for call termination API data
+ * - 📞 useEndCall hook return type
+ * - 🔄 Call termination function signature
+ * - 📊 State management types
+ * - 📅 Callback scheduling types
+ *
+ * @author CTI SDK Team
+ * @version 6.x.x
+ * @since 1.0.0
+ */
+
+/**
+ * 📞 End Call Payload Interface
+ *
+ * @interface EndCallPayload
+ * @description 📊 Defines the structure for call termination API payload data
+ *              Contains all necessary information for ending a call with proper disposition
+ *
+ * @properties
+ * - `action: string` - 🎯 API action type ("ENDCALL")
+ * - `disposition: string` - 📝 Call outcome classification
+ * - `userId: string` - 👤 Agent identifier
+ * - `processid: string` - ⚙️ Process identifier
+ * - `mobile_number: string` - 📱 Customer phone number
+ * - `set_followUp: string` - 📅 Follow-up requirement ("Y" or "N")
+ * - `callback_date: string` - 📅 Scheduled callback date
+ * - `callback_hrs: string` - 🕐 Scheduled callback hour
+ * - `callback_mins: string` - 🕐 Scheduled callback minute
+ * - `refno?: string` - 🔗 Optional call reference number
+ *
+ * @example
+ * ```typescript
+ * // Basic end call payload
+ * const endCallPayload: EndCallPayload = {
+ *   action: "ENDCALL",
+ *   disposition: "RES",
+ *   userId: "agent123",
+ *   processid: "proc001",
+ *   mobile_number: "1234567890",
+ *   set_followUp: "N",
+ *   callback_date: "",
+ *   callback_hrs: "",
+ *   callback_mins: ""
+ * };
+ *
+ * // With callback scheduling
+ * const endCallWithCallback: EndCallPayload = {
+ *   action: "ENDCALL",
+ *   disposition: "RES",
+ *   userId: "agent123",
+ *   processid: "proc001",
+ *   mobile_number: "1234567890",
+ *   set_followUp: "Y",
+ *   callback_date: "2024-01-15",
+ *   callback_hrs: "14",
+ *   callback_mins: "30"
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface EndCallPayload {
+	/**
+	 * 🎯 API action type
+	 * @description The action type for the API call
+	 * @type {string}
+	 */
+	action: string;
+
+	/**
+	 * 📝 Call outcome classification
+	 * @description Classification of how the call ended
+	 * @type {string}
+	 */
+	disposition: string;
+
+	/**
+	 * 👤 Agent identifier
+	 * @description Unique identifier for the agent ending the call
+	 * @type {string}
+	 */
+	userId: string;
+
+	/**
+	 * ⚙️ Process identifier
+	 * @description Unique identifier for the process
+	 * @type {string}
+	 */
+	processid: string;
+
+	/**
+	 * 📱 Customer phone number
+	 * @description Phone number of the customer
+	 * @type {string}
+	 */
+	mobile_number: string;
+
+	/**
+	 * 📅 Follow-up requirement
+	 * @description Whether a follow-up is required ("Y" or "N")
+	 * @type {string}
+	 */
+	set_followUp: string;
+
+	/**
+	 * 📅 Scheduled callback date
+	 * @description Date for scheduled callback (YYYY-MM-DD format)
+	 * @type {string}
+	 */
+	callback_date: string;
+
+	/**
+	 * 🕐 Scheduled callback hour
+	 * @description Hour for scheduled callback (0-23)
+	 * @type {string}
+	 */
+	callback_hrs: string;
+
+	/**
+	 * 🕐 Scheduled callback minute
+	 * @description Minute for scheduled callback (0-59)
+	 * @type {string}
+	 */
+	callback_mins: string;
+
+	/**
+	 * 🔗 Optional call reference number
+	 * @description Optional reference number for the call
+	 * @type {string | undefined}
+	 */
+	refno?: string;
+}
+
+/**
+ * 📞 Call Termination Function Type
  *
- * @returns {Function} Logout function
+ * @type CallTerminationFunction
+ * @description 🎯 Type definition for the call termination function
+ *              Handles call termination with disposition tracking and callback scheduling
+ *
+ * @param {EndCallData} data - 📊 Call termination data containing disposition and callback info
+ * @returns {Promise<any>} Promise that resolves with API response data or rejects with error
  *
  * @example
  * ```typescript
- * const logout = useLogout();
- * logout();
+ * const handleEndCall: CallTerminationFunction = async (data) => {
+ *   // Call termination logic
+ *   return await apiCall(data);
+ * };
  * ```
  *
  * @since 1.0.0
  * @author CTI SDK Team
  */
-declare function useLogout(): () => void;
+type CallTerminationFunction = (data: EndCallData) => Promise<any>;
+
+/**
+ * 📊 Hook State Management Types
+ *
+ * @type HookStateTypes
+ * @description 🎛️ Type definitions for all hook state variables
+ *              Provides type safety for loading, success, error, and data states
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type HookStateTypes = {
+	/**
+	 * ⏳ Loading state indicator
+	 * @description Boolean flag indicating if a call termination operation is in progress
+	 * @type {boolean}
+	 */
+	isLoading: boolean;
+
+	/**
+	 * ✅ Success state indicator
+	 * @description Boolean flag indicating if the last call termination was successful
+	 * @type {boolean}
+	 */
+	isSuccess: boolean;
+
+	/**
+	 * ❌ Error state indicator
+	 * @description Boolean flag indicating if the last call termination encountered an error
+	 * @type {boolean}
+	 */
+	isError: boolean;
+
+	/**
+	 * 🛡️ Error object
+	 * @description Contains the error object when a call termination fails
+	 * @type {any}
+	 */
+	error: any;
+
+	/**
+	 * 📊 Response data
+	 * @description Contains the response data from successful call terminations
+	 * @type {any}
+	 */
+	data: any;
+};
 
 /**
- * 🔚 End Call Hook
+ * 📞 useEndCall Hook Return Type
+ *
+ * @interface UseEndCallReturn
+ * @description 🎯 Complete return type for the useEndCall hook
+ *              Contains all functions and state for call termination functionality
+ *
+ * @properties
+ * - `handleEndCall: CallTerminationFunction` - 📞 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
+ * const EndCallButton = () => {
+ *   const hookReturn: UseEndCallReturn = useEndCall();
+ *   const {
+ *     handleEndCall,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = hookReturn;
+ *
+ *   // Use the hook functionality
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface UseEndCallReturn extends HookStateTypes {
+	/**
+	 * 📞 Call termination function
+	 * @description Handles call termination with disposition tracking and callback scheduling
+	 * @type {CallTerminationFunction}
+	 */
+	handleEndCall: CallTerminationFunction;
+}
+
+/**
+ * 📞 End Call Custom Hook
  *
  * @function useEndCall
- * @description Custom hook for handling call termination functionality.
- * Provides end call functionality with proper state management and cleanup.
+ * @description 🎯 Custom 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 {UseEndCallReturn} Hook return object containing:
+ *   - `handleEndCall: CallTerminationFunction` - 📞 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
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+declare const useEndCall: () => UseEndCallReturn;
+
+/**
+ * 📝 Disposition Types
+ *
+ * @type DispositionType
+ * @description 🎯 Type definitions for call disposition values
+ *              Used for call outcome classification
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type DispositionType = "RES" | "NI" | "CB" | "NA" | "BUSY" | "NO_ANSWER";
+
+/**
+ * 📅 Follow-up Types
+ *
+ * @type FollowUpType
+ * @description 🎯 Type definitions for follow-up requirement values
+ *              Used for callback scheduling
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type FollowUpType = "Y" | "N";
+
+/**
+ * ⚙️ Process Data Interface
+ *
+ * @interface ProcessData
+ * @description 📊 Type definition for process data structure
+ *              Contains information about the current process
+ *
+ * @properties
+ * - `process_id: number` - 🔢 Process identifier
+ * - `process_name: string` - 📝 Process name
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface ProcessData {
+	/**
+	 * 🔢 Process identifier
+	 * @description Unique identifier for the process
+	 * @type {number}
+	 */
+	process_id: number;
+
+	/**
+	 * 📝 Process name
+	 * @description Human-readable name of the process
+	 * @type {string}
+	 */
+	process_name: string;
+}
+
+/**
+ * 📅 End Call Data Interface
+ *
+ * @interface EndCallData
+ * @description 📊 Defines the structure for call termination input data
+ *              Contains disposition and callback information for ending calls
+ *
+ * @properties
+ * - `disposition?: string` - 📝 Call outcome classification (default: "RES")
+ * - `followUp?: string` - 📅 Follow-up requirement (default: "N")
+ * - `callbackDate?: string` - 📅 Scheduled callback date (default: "")
+ * - `callbackHrs?: string` - 🕐 Scheduled callback hour (default: "")
+ * - `callbackMins?: string` - 🕐 Scheduled callback minute (default: "")
+ *
+ * @example
+ * ```typescript
+ * // Basic end call data
+ * const endCallData: EndCallData = {
+ *   disposition: "RES",
+ *   followUp: "N"
+ * };
+ *
+ * // With callback scheduling
+ * const endCallWithCallback: EndCallData = {
+ *   disposition: "RES",
+ *   followUp: "Y",
+ *   callbackDate: "2024-01-15",
+ *   callbackHrs: "14",
+ *   callbackMins: "30"
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface EndCallData {
+	/**
+	 * 📝 Call outcome classification
+	 * @description How the call ended (default: "RES" for Resolved)
+	 * @type {string | undefined}
+	 */
+	disposition?: string;
+
+	/**
+	 * 📅 Follow-up requirement
+	 * @description Whether follow-up is required (default: "N" for No)
+	 * @type {string | undefined}
+	 */
+	followUp?: string;
+
+	/**
+	 * 📅 Scheduled callback date
+	 * @description Date for callback scheduling (YYYY-MM-DD format)
+	 * @type {string | undefined}
+	 */
+	callbackDate?: string;
+
+	/**
+	 * 🕐 Scheduled callback hour
+	 * @description Hour for callback scheduling (0-23)
+	 * @type {string | undefined}
+	 */
+	callbackHrs?: string;
+
+	/**
+	 * 🕐 Scheduled callback minute
+	 * @description Minute for callback scheduling (0-59)
+	 * @type {string | undefined}
+	 */
+	callbackMins?: string;
+}
+
+/**
+ * 📞 Call Data Interface
+ *
+ * @interface EndCallData
+ * @description 📊 Type definition for call data structure
+ *              Contains information about the current call
+ *
+ * @properties
+ * - `convox_id: string` - 🔗 Call reference identifier
+ * - `phone_number: string` - 📱 Customer phone number
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface EndCallData {
+	/**
+	 * 🔗 Call reference identifier
+	 * @description Unique identifier for the call
+	 * @type {string}
+	 */
+	convox_id: string;
+
+	/**
+	 * 📱 Customer phone number
+	 * @description Phone number of the customer
+	 * @type {string}
+	 */
+	phone_number: string;
+}
+
+/**
+ * 📋 Comprehensive Type Exports
+ *
+ * @description 📦 Re-exports all types for easy importing
+ *              Provides a single import point for all hook-related types
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   EndCallPayload,
+ *   UseEndCallReturn,
+ *   CallTerminationFunction,
+ *   EndCallData
+ * } from './useEndCall';
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+
+/**
+ * @fileoverview 🚪 TypeScript Declaration File for useLogout Hook
+ *
+ * This file contains TypeScript type definitions for the useLogout custom hook
+ * and its related interfaces. It provides comprehensive type safety and IntelliSense
+ * support for developers using the CTI SDK logout functionality.
+ *
+ * 🎯 Key Type Definitions:
+ * - 🚪 LogoutPayload interface for logout API data
+ * - 🚪 useLogout hook return type
+ * - 🔄 Logout function signature
+ * - 📊 State management types
+ * - 🗑️ Cleanup and storage management types
+ *
+ * @author CTI SDK Team
+ * @version 6.x.x
+ * @since 1.0.0
+ */
+
+/**
+ * 🚪 Logout Payload Interface
+ *
+ * @interface LogoutPayload
+ * @description 📊 Defines the structure for agent logout API payload data
+ *              Contains all necessary information for secure agent logout
+ *
+ * @properties
+ * - `action: string` - 🎯 API action type ("LOGOUTUSER")
+ * - `userId: string` - 👤 Agent identifier for logout
+ *
+ * @example
+ * ```typescript
+ * // Basic logout payload
+ * const logoutPayload: LogoutPayload = {
+ *   action: "LOGOUTUSER",
+ *   userId: "agent123"
+ * };
+ *
+ * // Usage in component
+ * const { logout } = useLogout();
+ * await logout();
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface LogoutPayload {
+	/**
+	 * 🎯 API action type
+	 * @description The action type for the logout API call
+	 * @type {string}
+	 */
+	action: string;
+
+	/**
+	 * 👤 Agent identifier
+	 * @description Unique identifier for the agent being logged out
+	 * @type {string}
+	 */
+	userId: string;
+}
+
+/**
+ * 🚪 Logout Function Type
+ *
+ * @type LogoutFunction
+ * @description 🎯 Type definition for the logout function
+ *              Handles secure agent logout with comprehensive cleanup procedures
+ *
+ * @returns {Promise<any>} Promise that resolves with API response data or rejects with error
+ *
+ * @example
+ * ```typescript
+ * const logout: LogoutFunction = async () => {
+ *   // Logout logic
+ *   return await apiCall();
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type LogoutFunction = () => Promise<any>;
+
+/**
+ * 📊 Hook State Management Types
+ *
+ * @type LogoutHookStateTypes
+ * @description 🎛️ Type definitions for all hook state variables
+ *              Provides type safety for loading, success, error, and data states
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type LogoutHookStateTypes = {
+	/**
+	 * ⏳ Loading state indicator
+	 * @description Boolean flag indicating if a logout operation is in progress
+	 * @type {boolean}
+	 */
+	isLoading: boolean;
+
+	/**
+	 * ✅ Success state indicator
+	 * @description Boolean flag indicating if the last logout was successful
+	 * @type {boolean}
+	 */
+	isSuccess: boolean;
+
+	/**
+	 * ❌ Error state indicator
+	 * @description Boolean flag indicating if the last logout encountered an error
+	 * @type {boolean}
+	 */
+	isError: boolean;
+
+	/**
+	 * 🛡️ Error object
+	 * @description Contains the error object when a logout fails
+	 * @type {any}
+	 */
+	error: any;
+
+	/**
+	 * 📊 Response data
+	 * @description Contains the response data from successful logout
+	 * @type {any}
+	 */
+	data: any;
+};
+
+/**
+ * 🚪 useLogout Hook Return Type
+ *
+ * @interface UseLogoutReturn
+ * @description 🎯 Complete return type for the useLogout hook
+ *              Contains all functions and state for logout functionality
+ *
+ * @properties
+ * - `logout: LogoutFunction` - 🚪 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
+ * const LogoutButton = () => {
+ *   const hookReturn: UseLogoutReturn = useLogout();
+ *   const {
+ *     logout,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = hookReturn;
+ *
+ *   // Use the hook functionality
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface UseLogoutReturn extends LogoutHookStateTypes {
+	/**
+	 * 🚪 Logout function
+	 * @description Handles secure agent logout with comprehensive cleanup procedures
+	 * @type {LogoutFunction}
+	 */
+	logout: LogoutFunction;
+}
+
+/**
+ * 🚪 Logout Custom Hook
+ *
+ * @function useLogout
+ * @description 🎯 Custom 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 {UseLogoutReturn} Hook return object containing:
+ *   - `logout: LogoutFunction` - 🚪 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);
+ *     }
+ *   };
  *
- * @returns {Function} End call function
+ *   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
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+declare const useLogout: () => UseLogoutReturn;
+
+/**
+ * 🗃️ SDK State Interface
+ *
+ * @interface SDKState
+ * @description 📊 Type definition for the SDK state structure
+ *              Used internally by the hook to access agent and call data
+ *
+ * @properties
+ * - `agentId: string` - 👤 Agent identifier
+ * - `process: ProcessData` - ⚙️ Process information
+ * - `callData: EndCallData` - 📞 Current call data
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface SDKState {
+	/**
+	 * 👤 Agent identifier
+	 * @description Unique identifier for the current agent
+	 * @type {string}
+	 */
+	agentId: string;
+
+	/**
+	 * ⚙️ Process information
+	 * @description Information about the current process
+	 * @type {ProcessData}
+	 */
+	process: ProcessData;
+
+	/**
+	 * 📞 Current call data
+	 * @description Data about the current call
+	 * @type {EndCallData}
+	 */
+	callData: EndCallData;
+}
+
+/**
+ * 🗃️ SDK State Interface
+ *
+ * @interface SDKState
+ * @description 📊 Type definition for the SDK state structure
+ *              Used internally by the hook to access agent data
+ *
+ * @properties
+ * - `agentId: string` - 👤 Agent identifier
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface SDKState {
+	/**
+	 * 👤 Agent identifier
+	 * @description Unique identifier for the current agent
+	 * @type {string}
+	 */
+	agentId: string;
+}
+
+/**
+ * 🗑️ Storage Management Types
+ *
+ * @type StorageType
+ * @description 🎯 Type definitions for storage management
+ *              Used for localStorage and sessionStorage operations
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type StorageType = "localStorage" | "sessionStorage";
+
+/**
+ * 🔄 Cleanup Operation Types
+ *
+ * @type CleanupOperation
+ * @description 🎯 Type definitions for cleanup operations
+ *              Used for state and storage cleanup procedures
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type CleanupOperation = "clearStorage" | "resetState" | "clearAll";
+
+/**
+ * 📋 Comprehensive Type Exports
+ *
+ * @description 📦 Re-exports all types for easy importing
+ *              Provides a single import point for all hook-related types
  *
  * @example
  * ```typescript
- * const endCall = useEndCall();
- * endCall();
+ * import {
+ *   LogoutPayload,
+ *   UseLogoutReturn,
+ *   LogoutFunction,
+ *   SDKState
+ * } from './useLogout';
  * ```
  *
  * @since 1.0.0
  * @author CTI SDK Team
  */
-declare function useEndCall(): () => void;
 
 /**
- * 📞 Click to Call Hook
+ * @fileoverview 📞 TypeScript Declaration File for useClickToCall Hook
+ *
+ * This file contains TypeScript type definitions for the useClickToCall custom hook
+ * and its related interfaces. It provides comprehensive type safety and IntelliSense
+ * support for developers using the CTI SDK.
+ *
+ * 🎯 Key Type Definitions:
+ * - 📱 StartCallPayload interface for call initiation data
+ * - 📞 useClickToCall hook return type
+ * - 🔄 Call initiation function signature
+ * - 📊 State management types
+ *
+ * @author CTI SDK Team
+ * @version 6.x.x
+ * @since 1.0.0
+ */
+
+/**
+ * 📱 Start Call Payload Interface
+ *
+ * @interface StartCallPayload
+ * @description 📊 Defines the structure for call initiation payload data
+ *              Contains the mobile number required to initiate a call
+ *
+ * @properties
+ * - `mobileNumber: string` - 📱 The phone number to call (required)
+ *
+ * @example
+ * ```typescript
+ * // Basic call initiation payload
+ * const callPayload: StartCallPayload = {
+ *   mobileNumber: "1234567890"
+ * };
+ *
+ * // Usage in component
+ * const { handleStartCall } = useClickToCall();
+ * await handleStartCall({ mobileNumber: "9876543210" });
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface StartCallPayload {
+	/**
+	 * 📱 Phone number to call
+	 * @description The mobile number that will be called
+	 * @type {string}
+	 */
+	mobileNumber: string;
+}
+
+/**
+ * 📞 Call Initiation Function Type
+ *
+ * @type CallInitiationFunction
+ * @description 🎯 Type definition for the call initiation function
+ *              Handles both regular calls and conference calls based on agent state
+ *
+ * @param {StartCallPayload} data - 📊 Call initiation data containing mobile number
+ * @returns {Promise<any>} Promise that resolves with API response data or rejects with error
+ *
+ * @example
+ * ```typescript
+ * const handleStartCall: CallInitiationFunction = async (data) => {
+ *   // Call initiation logic
+ *   return await apiCall(data);
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type CallInitiationFunction = (data: StartCallPayload) => Promise<any>;
+
+/**
+ * 📊 Hook State Management Types
+ *
+ * @type StartCalltHookStateTypes
+ * @description 🎛️ Type definitions for all hook state variables
+ *              Provides type safety for loading, success, error, and data states
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type StartCalltHookStateTypes = {
+	/**
+	 * ⏳ Loading state indicator
+	 * @description Boolean flag indicating if a call operation is currently in progress
+	 * @type {boolean}
+	 */
+	isLoading: boolean;
+
+	/**
+	 * ✅ Success state indicator
+	 * @description Boolean flag indicating if the last call operation was successful
+	 * @type {boolean}
+	 */
+	isSuccess: boolean;
+
+	/**
+	 * ❌ Error state indicator
+	 * @description Boolean flag indicating if the last call operation encountered an error
+	 * @type {boolean}
+	 */
+	isError: boolean;
+
+	/**
+	 * 🛡️ Error object
+	 * @description Contains the error object when a call operation fails
+	 * @type {any}
+	 */
+	error: any;
+
+	/**
+	 * 📊 Response data
+	 * @description Contains the response data from successful call operations
+	 * @type {any}
+	 */
+	data: any;
+};
+
+/**
+ * 📞 useClickToCall Hook Return Type
+ *
+ * @interface UseClickToCallReturn
+ * @description 🎯 Complete return type for the useClickToCall hook
+ *              Contains all functions and state for call initiation functionality
+ *
+ * @properties
+ * - `handleStartCall: CallInitiationFunction` - 📞 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 CallButton = () => {
+ *   const hookReturn: UseClickToCallReturn = useClickToCall();
+ *   const {
+ *     handleStartCall,
+ *     isLoading,
+ *     isSuccess,
+ *     isError,
+ *     error
+ *   } = hookReturn;
+ *
+ *   // Use the hook functionality
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface UseClickToCallReturn extends StartCalltHookStateTypes {
+	/**
+	 * 📞 Call initiation function
+	 * @description Handles call initiation with intelligent routing based on agent state
+	 * @type {CallInitiationFunction}
+	 */
+	handleStartCall: CallInitiationFunction;
+}
+
+/**
+ * 📞 Click-to-Call Custom Hook
  *
  * @function useClickToCall
- * @description Custom hook for handling click-to-call functionality.
- * Provides dialing functionality with proper state management and error handling.
+ * @description 🎯 Custom 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.
  *
- * @returns {Function} Click to call function
+ * @returns {UseClickToCallReturn} Hook return object containing:
+ *   - `handleStartCall: CallInitiationFunction` - 📞 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 clickToCall = useClickToCall();
- * clickToCall("1234567890");
+ * // 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>
+ *   );
+ * };
  * ```
  *
+ * @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
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+declare const useClickToCall: () => UseClickToCallReturn;
+
+/**
+ * 📊 Agent State Types
+ *
+ * @type AgentStatus
+ * @description 🎯 Type definitions for agent status values
+ *              Used internally by the hook to determine call routing logic
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+type AgentStatus = "IDLE" | "ONCALL" | "BUSY" | "AWAY" | "BREAK";
+
+/**
+ * 📞 Conference Line Interface
+ *
+ * @interface ConferenceLine
+ * @description 📊 Type definition for conference line data structure
+ *              Used internally by the hook for conference call management
+ *
+ * @properties
+ * - `line: number` - 📞 Line number identifier
+ * - `status: AgentStatus` - 📊 Current line status
+ * - `isCallStart: boolean` - ✅ Whether call is active on this line
+ * - `phone?: string` - 📱 Phone number for this line (optional)
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface ConferenceLine {
+	/**
+	 * 📞 Line number identifier
+	 * @description Unique identifier for the conference line
+	 * @type {number}
+	 */
+	line: number;
+
+	/**
+	 * 📊 Current line status
+	 * @description Status of the conference line
+	 * @type {AgentStatus}
+	 */
+	status: AgentStatus;
+
+	/**
+	 * ✅ Whether call is active on this line
+	 * @description Flag indicating if a call is currently active
+	 * @type {boolean}
+	 */
+	isCallStart: boolean;
+
+	/**
+	 * 📱 Phone number for this line
+	 * @description Phone number associated with this line (optional)
+	 * @type {string | undefined}
+	 */
+	phone?: string;
+}
+
+/**
+ * 📞 Call Data Interface
+ *
+ * @interface StartCalltData
+ * @description 📊 Type definition for call data structure
+ *              Contains information about the current call
+ *
+ * @properties
+ * - `status: AgentStatus` - 📊 Current call status
+ * - `agent_id: string` - 👤 Agent identifier
+ * - `process_name: string` - ⚙️ Process name
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface StartCalltData {
+	/**
+	 * 📊 Current call status
+	 * @description Status of the current call
+	 * @type {AgentStatus}
+	 */
+	status: AgentStatus;
+
+	/**
+	 * 👤 Agent identifier
+	 * @description Unique identifier for the agent
+	 * @type {string}
+	 */
+	agent_id: string;
+
+	/**
+	 * ⚙️ Process name
+	 * @description Name of the current process
+	 * @type {string}
+	 */
+	process_name: string;
+}
+
+/**
+ * 📡 API Response Interface
+ *
+ * @interface APIResponse
+ * @description 📊 Type definition for API response structure
+ *              Used for type safety in API call responses
+ *
+ * @properties
+ * - `data: any` - 📊 Response data
+ * - `status: number` - 📊 HTTP status code
+ * - `message?: string` - 📝 Optional response message
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface APIResponse {
+	/**
+	 * 📊 Response data
+	 * @description The main response data from the API
+	 * @type {any}
+	 */
+	data: any;
+
+	/**
+	 * 📊 HTTP status code
+	 * @description HTTP status code of the response
+	 * @type {number}
+	 */
+	status: number;
+
+	/**
+	 * 📝 Optional response message
+	 * @description Optional message from the API response
+	 * @type {string | undefined}
+	 */
+	message?: string;
+}
+
+/**
+ * 📡 API Response Interface
+ *
+ * @interface APIResponse
+ * @description 📊 Type definition for API response structure
+ *              Used for type safety in API call responses
+ *
+ * @properties
+ * - `data: any` - 📊 Response data
+ * - `status: number` - 📊 HTTP status code
+ * - `message?: string` - 📝 Optional response message
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface APIResponse {
+	/**
+	 * 📊 Response data
+	 * @description The main response data from the API
+	 * @type {any}
+	 */
+	data: any;
+
+	/**
+	 * 📊 HTTP status code
+	 * @description HTTP status code of the response
+	 * @type {number}
+	 */
+	status: number;
+
+	/**
+	 * 📝 Optional response message
+	 * @description Optional message from the API response
+	 * @type {string | undefined}
+	 */
+	message?: string;
+}
+
+/**
+ * 📡 API Response Interface
+ *
+ * @interface APIResponse
+ * @description 📊 Type definition for API response structure
+ *              Used for type safety in API call responses
+ *
+ * @properties
+ * - `data: any` - 📊 Response data
+ * - `status: number` - 📊 HTTP status code
+ * - `message?: string` - 📝 Optional response message
+ *
  * @since 1.0.0
  * @author CTI SDK Team
  */
-declare function useClickToCall(): (phoneNumber: string) => void;
+interface APIResponse {
+	/**
+	 * 📊 Response data
+	 * @description The main response data from the API
+	 * @type {any}
+	 */
+	data: any;
+
+	/**
+	 * 📊 HTTP status code
+	 * @description HTTP status code of the response
+	 * @type {number}
+	 */
+	status: number;
+
+	/**
+	 * 📝 Optional response message
+	 * @description Optional message from the API response
+	 * @type {string | undefined}
+	 */
+	message?: string;
+}
+
+/**
+ * 🛡️ Error Response Interface
+ *
+ * @interface ErrorResponse
+ * @description 📊 Type definition for error response structure
+ *              Used for type safety in error handling
+ *
+ * @properties
+ * - `message: string` - 📝 Error message
+ * - `code?: string` - 🔢 Optional error code
+ * - `details?: any` - 📊 Optional error details
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface ErrorResponse {
+	/**
+	 * 📝 Error message
+	 * @description Human-readable error message
+	 * @type {string}
+	 */
+	message: string;
+
+	/**
+	 * 🔢 Optional error code
+	 * @description Optional error code for programmatic handling
+	 * @type {string | undefined}
+	 */
+	code?: string;
+
+	/**
+	 * 📊 Optional error details
+	 * @description Optional additional error details
+	 * @type {any}
+	 */
+	details?: any;
+}
+
+/**
+ * 🛡️ Error Response Interface
+ *
+ * @interface ErrorResponse
+ * @description 📊 Type definition for error response structure
+ *              Used for type safety in error handling
+ *
+ * @properties
+ * - `message: string` - 📝 Error message
+ * - `code?: string` - 🔢 Optional error code
+ * - `details?: any` - 📊 Optional error details
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface ErrorResponse {
+	/**
+	 * 📝 Error message
+	 * @description Human-readable error message
+	 * @type {string}
+	 */
+	message: string;
+
+	/**
+	 * 🔢 Optional error code
+	 * @description Optional error code for programmatic handling
+	 * @type {string | undefined}
+	 */
+	code?: string;
+
+	/**
+	 * 📊 Optional error details
+	 * @description Optional additional error details
+	 * @type {any}
+	 */
+	details?: any;
+}
+
+/**
+ * 🛡️ Error Response Interface
+ *
+ * @interface ErrorResponse
+ * @description 📊 Type definition for error response structure
+ *              Used for type safety in error handling
+ *
+ * @properties
+ * - `message: string` - 📝 Error message
+ * - `code?: string` - 🔢 Optional error code
+ * - `details?: any` - 📊 Optional error details
+ *
+ * @since 1.0.0
+ * @author CTI SDK Team
+ */
+interface ErrorResponse {
+	/**
+	 * 📝 Error message
+	 * @description Human-readable error message
+	 * @type {string}
+	 */
+	message: string;
+
+	/**
+	 * 🔢 Optional error code
+	 * @description Optional error code for programmatic handling
+	 * @type {string | undefined}
+	 */
+	code?: string;
+
+	/**
+	 * 📊 Optional error details
+	 * @description Optional additional error details
+	 * @type {any}
+	 */
+	details?: any;
+}
 
-export { CallControlPanel, type CallControlPanelProps, type CallData, type InitSDKParams, type SDKConfig, getSDKVersion, initSDK, isSDKInitialized, useClickToCall, useEndCall, useLogout };
+export { type APIResponse, type AgentStatus, CallControlPanel, type CallControlPanelProps, type CallData, type CallInitiationFunction, type CallTerminationFunction, type CleanupOperation, type ConferenceLine, type DispositionType, type EndCallData, type EndCallPayload, type ErrorResponse, type FollowUpType, type HookStateTypes, type InitSDKParams, type LogoutFunction, type LogoutHookStateTypes, type LogoutPayload, type ProcessData, type SDKConfig, type SDKState, type StartCallPayload, type StartCalltData, type StartCalltHookStateTypes, type StorageType, type UseClickToCallReturn, type UseEndCallReturn, type UseLogoutReturn, getSDKVersion, initSDK, isSDKInitialized, useClickToCall, useEndCall, useLogout };