@koi-design/callkit 2.0.4 → 2.0.5-beta.10

package/CHANGELOG.md

@@ -0,0 +1,156 @@
+# v2.0.0
+
+## Breaking Changes
+
+- Removed user status, you can now maintain user status through events yourself
+- Separated registered status
+
+## What's Changed
+
+- Refactored SIP reconnection and socket reconnection mechanism
+- Separated call status from registered status, registered is now not associated with call status
+- Optimized log output
+- Optimized various details
+
+# v1.0.24
+
+## What's Changed
+
+- Added socket disconnection event. Added socket reconnection mechanism and reconnection failure event.
+
+# v1.0.23
+
+## What's Changed
+
+- login support encryptionMethod, The user can control whether to use internal encryption by setting a parameter.
+
+# v1.0.22
+
+## What's Changed
+
+- Code optimization
+
+# v1.0.21
+
+## What's Changed
+
+- Demo page, initialize CallKit address using production environment domain
+
+# v1.0.20
+
+## What's Changed
+
+- Added isAutoUpdateUserStatus optimization to config, defaults to true if not configured
+- User status changed: 1, "Offline"; 2, "Online"; 3, "Break"; 4, "In Call"; 5, "Training"; 6, "Processing"
+- Added html3 incoming call popup html + css reference example
+
+# v1.0.19
+
+## What's Changed
+
+- Added getInviteData to invite call invitation for data retrieval
+
+# v1.0.18
+
+## What's Changed
+
+- Added iceGatheringTimeout parameter
+
+# v1.0.17
+
+## What's Changed
+
+- Removed default handling for CALL_FAILED, currently requires user to handle actively
+
+# v1.0.14
+
+## What's Changed
+
+- Added user object, updated user status overall calls user internal functions
+- Added isAutoUpdateUserStatus to config to control whether user controls user status updates
+
+# v1.0.12
+
+## What's Changed
+
+- Active hang up, user status adjusted to break
+- Added AGENT_NO_ANSWER event
+
+# v1.0.11
+
+## What's Changed
+
+- Optimized user status
+
+  Login - Status: Unregistered
+
+  Sign in - Status: Idle
+
+  Dial success (received event: CALL_SUCCESS) - Status: Busy
+
+  Dial failed (received event: CALL_FAILED) - Status: Idle
+
+  Customer no answer (received event: CUSTOMER_NO_ANSWER) - Status: Break
+
+  Customer hang up (received event: CUSTOMER_HANG_UP) - Status: Break
+
+  Agent hang up (sent event: AGENT_HANG_UP) - Status: Break
+
+  Agent error (received event: ERROR) - Status: Break
+
+- Added isRegistered method
+
+# v1.0.10
+
+## What's Changed
+
+- Agent pick up event: AGENT_PICK_UP
+- Adjusted user status logic, login idle moved to sign in, sign out set to online
+
+# v1.0.9
+
+## What's Changed
+
+- Fixed active hang up callEnd duplicate trigger issue
+
+# v1.0.8
+
+## What's Changed
+
+- Fixed login detection triggered by sip signaling disConnect after logout
+
+# v1.0.7
+
+## What's Changed
+
+- Added forwarding of all socket events
+
+# v1.0.6
+
+## What's Changed
+
+- Support listening to multiple events with the same name
+
+# v1.0.5
+
+## What's Changed
+
+- Fixed socket exception reconnection
+
+# v1.0.4
+
+## What's Changed
+
+- Optimized socket connection
+
+# v1.0.3
+
+## What's Changed
+
+- Incoming call answer support
+
+# v1.0.2
+
+## What's Changed
+
+- Released initial version

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
-