@koi-design/callkit 2.0.5 → 2.1.0-beta.1

package/README.md

@@ -1,18 +1,20 @@
-# CallKit-1.0.21
+# @koi-design/callkit
 
 SIP-based Web Phone Call Toolkit
 
+Current Version: **2.0.5-beta.2**
+
 ## Installation
 
-### Method 1: Full Import
+### NPM Installation
 
-```html
-<script src="callkit/index.global.js"></script>
+```bash
+pnpm add @koi-design/callkit
 ```
 
-### Method 2: ESM/CJS Import
+### Dependencies
 
-Install the following dependencies:
+This package requires the following peer dependencies:
 
 ```json
 {
@@ -26,30 +28,43 @@ Install the following dependencies:
 
 ## Quick Start
 
-### Full Import Usage
+### Method 1: IIFE (Browser Global)
 
 ```html
-<script src="callkit/index.global.js"></script>
+<script src="koi-design/callkit/dist/index.global.js"></script>
 <script>
   const callKit = new WebCall.CallKit({
     host: 'https://example.com',
     log: 'debug',
     audioRef: () => document.querySelector('#audioRef'),
-    socket: 'wss://example.com/ws/in-call',
+    socket: 'wss://example.com/ws/in-call'
   });
 </script>
 ```
 
-### ESM Import Usage
+### Method 2: ESM Import
 
 ```js
-import { CallKit } from 'CallKit';
+import { CallKit } from '@koi-design/callkit';
 
 const callKit = new CallKit({
   host: 'https://example.com',
   log: 'debug',
   audioRef: () => document.querySelector('#audioRef'),
-  socket: 'wss://example.com/ws/in-call',
+  socket: 'wss://example.com/ws/in-call'
+});
+```
+
+### Method 3: CommonJS Import
+
+```js
+const { CallKit } = require('@koi-design/callkit');
+
+const callKit = new CallKit({
+  host: 'https://example.com',
+  log: 'debug',
+  audioRef: () => document.querySelector('#audioRef'),
+  socket: 'wss://example.com/ws/in-call'
 });
 ```
 
@@ -72,10 +87,40 @@ interface CallKitConfig {
   constrains?: WebrtcConstranis;
 
   // Log level
-  log?: 'debug' | 'log' | 'warn' | 'error' | 'silent';
+  log?: 'info' | 'success' | 'warn' | 'error' | 'silent';
+
+  // Reconnection configuration
+  reconnect?: {
+    // SIP reconnection configuration
+    sip: {
+      enabled: boolean; // Enable SIP reconnection (default: true)
+      maxAttempts: number; // Maximum reconnection attempts (default: 5)
+      delay: number; // Reconnection delay in ms (default: 3000)
+    // In-call socket reconnection configuration
+    incall: {
+      enabled: boolean; // Enable in-call reconnection (default: true)
+      maxAttempts: number; // Maximum reconnection attempts (default: 5)
+      delay: number; // Reconnection delay in ms (default: 3000)
+      pingInterval: number; // Heartbeat interval in ms (default: 30000)
+      pingTimeout: number; // Heartbeat timeout in ms (default: 10000)
+    };
+  };
+
+  // Track logs configuration
+  trackLogs?: {
+    enabled: boolean; // Enable log tracking (default: false)
+    interval: number; // Log upload interval in ms (default: 10000)
+    maxSize: number; // Maximum log buffer size (default: 100)
+  };
+}
 
-  // User manually maintains sending user status requests
-  isAutoUpdateUserStatus: boolean;
+interface WebrtcConstranis {
+  audio: {
+    autoGainControl?: boolean;
+    noiseSuppression?: boolean;
+    echoCancellation?: boolean;
+  };
+  video: false;
 }
 ```
 
@@ -84,13 +129,29 @@ interface CallKitConfig {
 ```ts
 interface CallKit {
   // User login
-  login(username: string, password: string): Promise<void>;
+  login(
+    username: string,
+    password: string,
+    extra?: {
+      encryptionMethod?: 'INTERNAL' | 'NONE';
+      [key: string]: any;
+    }
+  ): Promise<void>;
 
   // User logout
-  logout(): Promise<void>;
+  logout(options?: { isReset?: boolean }): Promise<void>;
 
   // Initiate call
-  call(): Promise<void>;
+  call(
+    extno: string | number,
+    options?: {
+      sourceType?: number;
+      workOrderId?: string;
+    }
+  ): Promise<void>;
+
+  // Transfer call
+  refer(uri: string, options?: any): Promise<void>;
 
   // SIP registration
   register(): Promise<void>;
@@ -107,52 +168,66 @@ interface CallKit {
   // Release hold
   unhold(): void;
 
-  // Set free status
-  setFree(): Promise<void>;
+  // Mute microphone
+  mute(): void;
 
-  // Set nap status
-  setSleep(): Promise<void>;
+  // Unmute microphone
+  unmute(): void;
 
-  // Set busy status
-  setBusy(): Promise<void>;
+  // Set user status (manually)
+  setUserStatus(status: number): Promise<void>;
 
   // Reset all states
-  reset(): Promise<void>;
+  reset(config?: { force?: boolean }): Promise<void>;
 
   // Event listener
   on(event: string, callback: Function): void;
+
+  // Remove event listener
+  off(event: string, callback?: Function): void;
+
+  // Remove all event listeners
+  removeAllListeners(): void;
 }
 ```
 
 ### Event List
 
-#### Status Events
+#### Status Change Events
 
-- `userStatusChange` - User status change
-- `loginChange` - Login status change
-- `registerChange` - Registration status change
-- `callStatusChange` - Call status change
-- `holdChange` - Hold status change
-- `muteChange` - Mute status change
+- `loginChange` - Login status change (param: boolean)
+- `registerChange` - Registration status change (param: boolean)
+- `callStatusChange` - Call status change (param: CallStatus)
+- `callIdChange` - Call ID change (param: string)
+- `holdChange` - Hold status change (param: boolean)
+- `muteChange` - Mute status change (param: boolean)
 
 #### Call Events
 
-- `invite` - Received call invitation (with accept, reject, getInviteData callback functions)
-- `connecting` - Connecting (with timestamp parameter)
-- `ringing` - Remote party ringing (with timestamp parameter)
-- `pickUp` - Remote party answered (with timestamp parameter)
-- `agentPickUp` - Agent connected
-- `noAnswer` - No answer
-- `callEnd` - Call ended
-- `callCdr` - Call record push
+- `invite` - Received incoming call invitation
+  - Callback params: `{ accept: Function, reject: Function, getInviteData: Function }`
+- `outgoingInvite` - Received outgoing call invitation
+- `connecting` - Call connecting (param: timestamp)
+- `ringing` - Remote party ringing (param: timestamp)
+- `pickUp` - Remote party answered (param: timestamp)
+- `agentPickUp` - Agent connected (param: timestamp)
+- `hangUp` - Remote party hung up (param: timestamp)
+- `noAnswer` - No answer (param: timestamp)
+- `callEnd` - Call ended (param: timestamp)
+- `callCdr` - Call detail record push (param: CDR data)
 
-#### Error Events
+#### Connection Events
 
-- `error` - Error occurred
+- `IncallConnectEvent` - In-call socket connection event
+- `sipConnectEvent` - SIP connection event
+- `sipRegistererEvent` - SIP registerer event
+- `sipSessionEvent` - SIP session event
 
-#### Server Socket Events
+#### System Events
 
-- `socketEvent` Forward all socket events
+- `log` - System log event
+- `error` - Error occurred (param: { code: number, message: string })
+- `socketEvent` - Forward all socket events (param: socket message)
 
 ## Status Codes
 
@@ -161,31 +236,40 @@ interface CallKit {
 ```js
 const CallStatus = {
   init: 0, // Initial state/hung up
-  registered: 1, // Registered
   connecting: 2, // Connecting
-  holding: 3, // Call hold
   ringing: 4, // Ringing
-  calling: 5, // In call
+  calling: 5 // In call
 };
 ```
 
+> Note: In version 2.0.0+, `registered` and `holding` statuses have been removed. Registration status is now tracked separately via the `registerChange` event.
+
 ### User Status
 
+> Note: In version 2.0.0+, user status management has been removed from CallKit. You should maintain user status through your own application using the `setUserStatus` method.
+
 ```js
+// Example user status codes (define as needed in your application)
 const UserStatus = {
   offline: 1, // Offline
   online: 2, // Online & Free
   catNap: 3, // Cat Nap
   busy: 4, // Busy
   training: 5, // Training
-  processing: 6, // Processing
+  processing: 6 // Processing
 };
+
+// Set user status manually
+await callKit.setUserStatus(UserStatus.online);
 ```
 
 ### Error Codes
 
 ```js
 const ErrorCode = {
+  // Unknown error
+  UNKNOWN_ERROR: -1,
+
   // API errors (1000xxx)
   API_USER_LOGIN_ERROR: 1000001, // User login failed
   API_USER_STATUS_UPDATE_ERROR: 1000002, // Update user status failed
@@ -198,14 +282,19 @@ const ErrorCode = {
   WEBRTC_HOLE_STATUS_ERROR: 2000004, // Call hold failed
   WEBRTC_AUDIO_PLAYER_ERROR: 2000005, // Audio player does not exist
   WEBRTC_AUDIO_PLAY_ERROR: 2000006, // Audio playback failed
+  WEBRTC_USER_AGENT_ERROR: 2000007, // User agent startup failed
+  WEBRTC_CALL_INVITE_ERROR: 2000008, // Call request failed
+  WEBRTC_REGISTER_ERROR: 2000009, // Register request failed
+  WEBRTC_MUTE_STATUS_ERROR: 2000010, // Mute failed
+  WEBRTC_CANCEL_REGISTER_ERROR: 2000011, // Unregister failed
+  WEBRTC_MUTE_ERROR: 2000012, // Mute operation failed
 
   // WebSocket errors (3000xxx)
   SOCKET_CONNECT_ERROR: 3000001, // Connection exception
   SOCKET_PING_TIMEOUT: 3000002, // Ping timeout
   SOKET_SERVER_ERROR: 3000003, // Server exception
   SOCKET_CALL_ERROR: 3000004, // Call failed
-
-  UNKNOWN_ERROR: -1, // Unknown error
+  SOCKET_RECONNECT_FAILED: 3000005 // Reconnection limit exceeded
 };
 ```
 
@@ -217,17 +306,26 @@ const ErrorCode = {
 callKit.on('callStatusChange', (status) => {
   const statusMap = {
     0: 'Initial state',
-    1: 'Registered',
     2: 'Connecting',
-    3: 'Call on hold',
     4: 'Ringing',
-    5: 'In call',
+    5: 'In call'
   };
   console.log('Current status:', statusMap[status]);
 });
 ```
 
-### Q2: How to get call duration?
+### Q2: How to listen for registration status changes?
+
+```js
+callKit.on('registerChange', (isRegistered) => {
+  console.log(
+    'Registration status:',
+    isRegistered ? 'Registered' : 'Unregistered'
+  );
+});
+```
+
+### Q3: How to get call duration?
 
 ```js
 let startTime;
@@ -242,7 +340,23 @@ callKit.on('callEnd', (date) => {
 });
 ```
 
-### Q3: How to handle errors?
+### Q4: How to handle incoming calls?
+
+```js
+callKit.on('invite', ({ accept, reject, getInviteData }) => {
+  // Get call data
+  const inviteData = getInviteData();
+  console.log('Incoming call:', inviteData);
+
+  // Accept the call
+  accept();
+
+  // Or reject the call
+  // reject();
+});
+```
+
+### Q5: How to handle errors?
 
 ```js
 callKit.on('error', (error) => {
@@ -256,17 +370,127 @@ callKit.on('error', (error) => {
     case 2000002:
       // Handle not logged in error
       break;
-    // Remove CALL_FAILED default handling, at this stage, users need to handle it actively
+    case 3000005:
+      // Handle reconnection failure
+      break;
     // ...other error handling
   }
 });
 ```
 
+### Q6: How to handle reconnection?
+
+```js
+// Listen to reconnection events
+callKit.on('IncallConnectEvent', (event) => {
+  console.log('In-call connection event:', event);
+});
+
+callKit.on('sipConnectEvent', (event) => {
+  console.log('SIP connection event:', event);
+});
+
+// Configure reconnection options
+const callKit = new CallKit({
+  host: 'https://example.com',
+  socket: 'wss://example.com/ws/in-call',
+  audioRef: () => document.querySelector('#audioRef'),
+  reconnect: {
+    sip: {
+      enabled: true,
+      maxAttempts: 5,
+      delay: 3000
+    },
+    incall: {
+      enabled: true,
+      maxAttempts: 5,
+      delay: 3000
+    }
+  }
+});
+```
+
+### Q7: How to use mute/unmute?
+
+```js
+// Mute microphone
+callKit.mute();
+
+// Unmute microphone
+callKit.unmute();
+
+// Listen to mute status changes
+callKit.on('muteChange', (isMuted) => {
+  console.log('Mute status:', isMuted ? 'Muted' : 'Unmuted');
+});
+```
+
+### Q8: How to use hold/unhold?
+
+```js
+// Hold call
+callKit.hold();
+
+// Unhold call
+callKit.unhold();
+
+// Listen to hold status changes
+callKit.on('holdChange', (isHeld) => {
+  console.log('Hold status:', isHeld ? 'On hold' : 'Active');
+});
+```
+
 ## More Information
 
 For complete TypeScript type definitions, please refer to [index.d.ts](./dist/index.d.ts)
 
+## Breaking Changes in v2.0.0
+
+### Major Changes
+
+1. **User Status Management Removed**
+
+   - CallKit no longer automatically manages user status
+   - Use `setUserStatus()` method to manually maintain user status
+
+2. **Registration Status Separated**
+
+   - Registration status is no longer part of call status
+   - Use `registerChange` event to track registration status independently
+
+3. **Call Status Simplified**
+
+   - Removed `registered` (1) status - use `registerChange` event instead
+   - Removed `holding` (3) status - use `holdChange` event instead
+   - Current statuses: `init` (0), `connecting` (2), `ringing` (4), `calling` (5)
+
+4. **Enhanced Reconnection Mechanism**
+
+   - Completely refactored SIP and socket reconnection logic
+   - Added configurable reconnection options for both SIP and in-call connections
+   - New error code: `SOCKET_RECONNECT_FAILED` (3000005)
+
+5. **New Methods**
+
+   - `mute()` / `unmute()` - Control microphone muting
+   - `refer(uri, options)` - Transfer calls
+   - `off(event, callback)` - Remove specific event listeners
+   - `removeAllListeners()` - Remove all event listeners
+   - `setUserStatus(status)` - Manually set user status
+
+6. **New Events**
+   - `callIdChange` - Call ID change event
+   - `outgoingInvite` - Outgoing call invitation event
+   - `hangUp` - Remote party hang up event
+   - `IncallConnectEvent` - In-call socket connection event
+   - `sipConnectEvent` - SIP connection event
+   - `sipRegistererEvent` - SIP registerer event
+   - `sipSessionEvent` - SIP session event
+
+### Migration Guide
+
+Please refer to [MIGRATION.md](./MIGRATION.md) for detailed migration instructions from v1.x to v2.0.
+
 ## License
 
 MIT
-

package/dist/index.d.ts

@@ -8,11 +8,13 @@ declare class Api {
     login(params: {
         userName: string;
         password: string;
+        timestamp: number;
     }): Promise<any>;
     loginOut(params: {
         sessionId: string;
+        timestamp: number;
     }): Promise<any>;
-    trackLogs(log: string): Promise<any>;
+    trackLogs(log: string): Promise<void>;
     /**
      *
      * @param params agentId status
@@ -74,7 +76,7 @@ declare class Socket {
     /**
      * @description connect auth state
      * @default {
-     *   satrtConfirm: false,
+     *   startConfirm: false,
      *   isConnected: false,
      *   isReconnecting: false,
      *   isAuthenticated: false,
@@ -82,16 +84,23 @@ declare class Socket {
      * }
      */
     private connectAuthState;
-    get satrtConfirm(): boolean;
+    get startConfirm(): boolean;
     get isError(): boolean;
     constructor(callKit: CallKit);
+    get reconnectConfig(): {
+        enabled?: boolean;
+        maxAttempts?: number;
+        delay?: number;
+        pingInterval?: number;
+        pingTimeout?: number;
+    };
     init(): void;
-    private getSocketConfig;
     private setConnectAuthState;
     private handleDisconnect;
     private clearWebSocket;
     private connect;
     private onOpen;
+    private cleanReconnectState;
     private resetConnectState;
     private onClose;
     private onError;
@@ -104,7 +113,7 @@ declare class Socket {
      * reset socket connection and all states
      */
     reset(config?: {
-        focus?: boolean;
+        force?: boolean;
     }): Promise<void>;
     private attemptReconnect;
 }
@@ -121,11 +130,14 @@ interface IConfig {
     version: string;
     host: string;
     log: LoggerLevel;
-    trackLogs: TrackLogsConfig;
+    trackLogs: Partial<TrackLogsConfig>;
     audioRef?: HTMLAudioElement | (() => HTMLAudioElement);
     constrains: WebrtcConstranis;
     socket: string;
-    reconnect?: SocketConfig;
+    reconnect?: {
+        sip?: Partial<SocketConfig>;
+        incall?: Partial<SocketConfig>;
+    };
     userInfo: {
         wsUrl: string;
         sessionId: string;
@@ -154,11 +166,22 @@ declare class Config {
     getConfig: () => IConfig;
     setConfig: (key: string, value: any) => Promise<void>;
     setUserInfo: (key: string, value: any) => Promise<void>;
-    reset: () => Promise<void>;
+    reset: (form: string) => Promise<void>;
     validate: () => boolean;
     isLogin: () => boolean;
     check(): boolean;
-    getTrackLogsConfig(): TrackLogsConfig;
+    getTrackLogsConfig(): {
+        enabled: boolean;
+        interval: number;
+        maxSize: number;
+    };
+    getReconnectConfig(type: 'sip' | 'incall'): {
+        enabled?: boolean;
+        maxAttempts?: number;
+        delay?: number;
+        pingInterval?: number;
+        pingTimeout?: number;
+    };
     enableTrackLogs(enabled: boolean): void;
 }
 
@@ -369,10 +392,6 @@ declare class Call {
 type CallStatusType = (typeof CallStatus)[keyof typeof CallStatus];
 declare class Connect {
     callKit: CallKit;
-    /**
-     *@description  Reconnect config
-     */
-    private reconnectConfig;
     /**
      *@description  Whether muted
      */
@@ -397,6 +416,10 @@ declare class Connect {
      *@description  Whether it's a re-connected
      */
     isReConnected: boolean;
+    /**
+     *@description  Whether it's a referring
+     */
+    isRefering: boolean;
     /**
      *@description  Whether it's an outgoing call
      */
@@ -410,7 +433,18 @@ declare class Connect {
      */
     hasInvite: boolean;
     constructor(callKit: CallKit);
-    currentCallId: string | null;
+    get reconnectConfig(): {
+        enabled?: boolean;
+        maxAttempts?: number;
+        delay?: number;
+        pingInterval?: number;
+        pingTimeout?: number;
+    };
+    private currentCallId;
+    getCurrentCallId(): string | null;
+    setRefering(refering: boolean): void;
+    private setIsReConnected;
+    setOutgoing(outgoing: boolean): void;
     setCallId(callId: string | null): void;
     reset(): Promise<void>;
     private getAduioReference;
@@ -446,11 +480,12 @@ declare class Connect {
      * @returns
      */
     isInit(): boolean;
-    private heartbeatInterval?;
-    private heartbeatFlag;
-    clearHeartbeat(): void;
-    startHeartbeat(): void;
     socketTriggerHangup(callId: string): void;
+    /**
+     * Setup registerer and bind stateChange listener
+     * @private
+     */
+    private setupRegisterer;
     register(): Promise<void>;
     private reconnectTimer?;
     private reconnectAttempts;
@@ -492,8 +527,12 @@ interface CallKitConfig {
     socket: string;
     constrains?: WebrtcConstranis;
     log?: LoggerLevel;
+    reconnect?: {
+        sip?: Partial<SocketConfig>;
+        incall?: Partial<SocketConfig>;
+    };
 }
-type ConfigEntity = CallKitConfig & Partial<IConfig>;
+type ConfigEntity = Partial<IConfig> & CallKitConfig;
 type kitEventType = (typeof KitEvent)[keyof typeof KitEvent];
 interface Listener {
     event: kitEventType;
@@ -527,15 +566,18 @@ declare class CallKit {
      * set userstatus
      * @param status
      */
-    setUserStatus(status: number): Promise<void>;
-    protected _reset(config?: {
-        focus?: boolean;
+    setUserStatus(status: number, extra?: {
+        [key: string]: any;
     }): Promise<void>;
     /**
      * reset callkit
      * @description recover the callkit to the initial state
+     * @default force is false
+     * @param config.force is true, the callkit reset socket connection and all states
      */
-    reset(): Promise<void>;
+    reset(config?: {
+        force?: boolean;
+    }): Promise<void>;
     on(event: kitEventType, callback: (...args: any[]) => void): void;
     off(event: kitEventType, callback?: (...args: any[]) => void): void;
     removeAllListeners(): void;