@koi-design/callkit 1.0.22

package/README.md

@@ -0,0 +1,272 @@
+# CallKit-1.0.21
+
+SIP-based Web Phone Call Toolkit
+
+## Installation
+
+### Method 1: Full Import
+
+```html
+<script src="callkit/index.global.js"></script>
+```
+
+### Method 2: ESM/CJS Import
+
+Install the following dependencies:
+
+```json
+{
+  "dependencies": {
+    "axios": "~0.26.1",
+    "blueimp-md5": "^2.12.0",
+    "sip.js": "^0.21.2"
+  }
+}
+```
+
+## Quick Start
+
+### Full Import Usage
+
+```html
+<script src="callkit/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',
+  });
+</script>
+```
+
+### ESM Import Usage
+
+```js
+import { CallKit } from 'CallKit';
+
+const callKit = new CallKit({
+  host: 'https://example.com',
+  log: 'debug',
+  audioRef: () => document.querySelector('#audioRef'),
+  socket: 'wss://example.com/ws/in-call',
+});
+```
+
+## API Documentation
+
+### Configuration Options
+
+```ts
+interface CallKitConfig {
+  // Request host address
+  host: string;
+
+  // Audio element object
+  audioRef: HTMLAudioElement | (() => HTMLAudioElement);
+
+  // WebSocket address
+  socket: string;
+
+  // WebRTC constraint configuration
+  constrains?: WebrtcConstranis;
+
+  // Log level
+  log?: 'debug' | 'log' | 'warn' | 'error' | 'silent';
+
+  // User manually maintains sending user status requests
+  isAutoUpdateUserStatus: boolean;
+}
+```
+
+### Instance Methods
+
+```ts
+interface CallKit {
+  // User login
+  login(username: string, password: string): Promise<void>;
+
+  // User logout
+  logout(): Promise<void>;
+
+  // Initiate call
+  call(): Promise<void>;
+
+  // SIP registration
+  register(): Promise<void>;
+
+  // SIP unregistration
+  unregister(): Promise<void>;
+
+  // Hang up call
+  hangup(): Promise<void>;
+
+  // Call hold
+  hold(): void;
+
+  // Release hold
+  unhold(): void;
+
+  // Set free status
+  setFree(): Promise<void>;
+
+  // Set nap status
+  setSleep(): Promise<void>;
+
+  // Set busy status
+  setBusy(): Promise<void>;
+
+  // Reset all states
+  reset(): Promise<void>;
+
+  // Event listener
+  on(event: string, callback: Function): void;
+}
+```
+
+### Event List
+
+#### Status 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
+
+#### 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
+
+#### Error Events
+
+- `error` - Error occurred
+
+#### Server Socket Events
+
+- `socketEvent` Forward all socket events
+
+## Status Codes
+
+### Call Status
+
+```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
+};
+```
+
+### User Status
+
+```js
+const UserStatus = {
+  offline: 1, // Offline
+  online: 2, // Online & Free
+  catNap: 3, // Cat Nap
+  busy: 4, // Busy
+  training: 5, // Training
+  processing: 6, // Processing
+};
+```
+
+### Error Codes
+
+```js
+const ErrorCode = {
+  // API errors (1000xxx)
+  API_USER_LOGIN_ERROR: 1000001, // User login failed
+  API_USER_STATUS_UPDATE_ERROR: 1000002, // Update user status failed
+  API_USER_LOGOUT_ERROR: 1000003, // User logout failed
+
+  // WebRTC errors (2000xxx)
+  CONNECT_CALL_STATUS_ERROR: 2000001, // Call status exception
+  USER_NOT_LOGIN: 2000002, // User not logged in
+  WEBRTC_USER_MEDIA_ERROR: 2000003, // WebRTC not supported
+  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
+
+  // 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
+};
+```
+
+## FAQ
+
+### Q1: How to listen for call status changes?
+
+```js
+callKit.on('callStatusChange', (status) => {
+  const statusMap = {
+    0: 'Initial state',
+    1: 'Registered',
+    2: 'Connecting',
+    3: 'Call on hold',
+    4: 'Ringing',
+    5: 'In call',
+  };
+  console.log('Current status:', statusMap[status]);
+});
+```
+
+### Q2: How to get call duration?
+
+```js
+let startTime;
+
+callKit.on('pickUp', (date) => {
+  startTime = date;
+});
+
+callKit.on('callEnd', (date) => {
+  const duration = date - startTime;
+  console.log('Call duration (ms):', duration);
+});
+```
+
+### Q3: How to handle errors?
+
+```js
+callKit.on('error', (error) => {
+  console.error('Error code:', error.code);
+  console.error('Error message:', error.message);
+
+  switch (error.code) {
+    case 1000001:
+      // Handle login failure
+      break;
+    case 2000002:
+      // Handle not logged in error
+      break;
+    // Remove CALL_FAILED default handling, at this stage, users need to handle it actively
+    // ...other error handling
+  }
+});
+```
+
+## More Information
+
+For complete TypeScript type definitions, please refer to [index.d.ts](./dist/index.d.ts)
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,436 @@
+import { Invitation, UserAgent, Registerer } from 'sip.js';
+
+declare class Api {
+    private callKit;
+    constructor(callKit: CallKit);
+    login(params: {
+        userName: string;
+        password: string;
+    }): Promise<any>;
+    loginOut(params: {
+        sessionId: string;
+    }): Promise<any>;
+    /**
+     *
+     * @param params agentId userStatus
+     * @description userStatus: Logout(1, "unregistered"), Free(2, "free"), Break(3, "nap"), Busy(4, "busy")
+     * @returns
+     */
+    setUserStatus(params: any): Promise<any>;
+    private post;
+}
+
+declare class Call {
+    private callKit;
+    constructor(callKit: CallKit);
+    callStart(): Promise<void>;
+    /**
+     * Hang up
+     * @param isUnprompted Whether to actively hang up
+     * @param isError Whether an error occurred
+     * @returns
+     */
+    callEnd(isUnprompted?: boolean, isError?: boolean): Promise<void>;
+    callHold(): Promise<void>;
+    callUnhold(): Promise<void>;
+}
+
+type LoggerLevel = 'debug' | 'log' | 'warn' | 'error' | 'silent';
+declare class Logger {
+    prefix: string;
+    level: LoggerLevel;
+    private callKit;
+    constructor(callKit: CallKit, level?: LoggerLevel);
+    setLevel(level: LoggerLevel): void;
+    debug(msg: any, extra?: Object): void;
+    log(msg: any, extra?: Object): void;
+    warn(msg: any, extra?: Object): void;
+    error(msg: any, extra?: any): void;
+    output(color: string): (msg: any, extra?: Object) => void;
+}
+
+declare const CallStatus: {
+    /**
+     * Initial state/Hang up
+     */
+    init: number;
+    /**
+     * Registered
+     */
+    registered: number;
+    /**
+     * Connecting
+     */
+    connecting: number;
+    /**
+     * Call on hold
+     */
+    holding: number;
+    /**
+     * Ringing
+     */
+    ringing: number;
+    /**
+     * In call
+     */
+    calling: number;
+};
+declare const KitEvent: {
+    /**
+     * User status change
+     */
+    KIT_USER_STATUS_CHANGE: string;
+    /**
+     * User login status change
+     */
+    KIT_LOGIN_CHANGE: string;
+    /**
+     * Registration status change
+     */
+    KIT_REGISTER_CHANGE: string;
+    /**
+     * Call status change
+     */
+    KIT_CALL_STATUS_CHANGE: string;
+    /**
+     * Hold status change
+     */
+    KIT_SET_HOLD: string;
+    /**
+     * Mute status change
+     */
+    KIT_SET_MUTE: string;
+    /**
+     * Error
+     */
+    KIT_ERROR: string;
+    /**
+     * Server initiated call
+     */
+    KIT_INVITE: string;
+    /**
+     * Connecting
+     */
+    CALL_CONNECTING: string;
+    /**
+     * Customer ringing
+     */
+    CALL_RINGING: string;
+    /**
+     * Agent pick up
+     */
+    AGENT_PICK_UP: string;
+    /**
+     * Customer answer
+     */
+    CALL_PICK_UP: string;
+    /**
+     * Customer no response
+     */
+    CALL_NO_ANSWER: string;
+    /**
+     * Customer hang up
+     */
+    CALL_HANG_UP: string;
+    /**
+     * Call end
+     */
+    CALL_END: string;
+    /**
+     * Call detail record push
+     */
+    CALL_CDR: string;
+    /**
+     * Forward all socket events
+     */
+    SERVER_SOCKET_EVENT: string;
+    /**
+     * User status change
+     */
+    USER_STATUS_CHANGE: string;
+};
+declare const SocketSendEvent: {
+    /**
+     * ping
+     */
+    PING: string;
+    /**
+     * Start
+     */
+    START: string;
+    /**
+     * Hang up
+     */
+    AGENT_HANGUP: string;
+    /**
+     * Cancel
+     */
+    CALL_CANCEL: string;
+    /**
+     * Hold
+     */
+    HOLD: string;
+    /**
+     * Unhold
+     */
+    UNHOLD: string;
+    /**
+     * Call
+     */
+    CALL: string;
+    /**
+     * End
+     */
+    END: string;
+};
+
+type SocketSendEventType = (typeof SocketSendEvent)[keyof typeof SocketSendEvent];
+interface SocketConfig {
+    enabled: boolean;
+    maxAttempts: number;
+    delay: number;
+    backoffMultiplier: number;
+    pingInterval: number;
+    pingTimeout: number;
+}
+declare class Socket {
+    private callKit;
+    private ws?;
+    private socketConfig;
+    lastPingTime: any;
+    isConnected: boolean;
+    pingTimer?: number;
+    recivedClose: boolean;
+    satrtConfirm: boolean;
+    private reconnectTimer?;
+    private isReconnecting;
+    private reconnectAttempts;
+    constructor(callKit: CallKit);
+    init(): void;
+    private connect;
+    private onOpen;
+    private onClose;
+    private onError;
+    private onMessage;
+    send(event: SocketSendEventType, message?: any): void;
+    /**
+     * Attempt to close socket, need to wait for server confirmation
+     * @returns
+     */
+    requestClose(): Promise<boolean>;
+    private ping;
+    private checkPing;
+    /**
+     *
+     * @param isWaitConfirm Whether need to wait for close confirmation
+     */
+    reset(isWaitConfirm?: boolean): Promise<void>;
+    private attemptReconnect;
+}
+
+interface WebrtcConstranis {
+    audio: {
+        autoGainControl?: boolean;
+        noiseSuppression?: boolean;
+        echoCancellation?: boolean;
+    };
+    video: false;
+}
+interface IConfig {
+    version: string;
+    host: string;
+    log: LoggerLevel;
+    audioRef?: HTMLAudioElement | (() => HTMLAudioElement);
+    constrains: WebrtcConstranis;
+    socket: string;
+    reconnect?: SocketConfig;
+    userInfo: {
+        wsUrl: string;
+        sessionId: string;
+        username: string;
+        password: string;
+        extno: string;
+        userPart: string;
+        agentId: string;
+        fsUserId: string;
+        fsPassword: string;
+        fsIp: string;
+        fsPort: string;
+        iceInfo: string[];
+        iceGatheringTimeout: number;
+    };
+    isAutoUpdateUserStatus: boolean;
+}
+declare class Config {
+    callKit: CallKit;
+    constructor(callKit: CallKit);
+    config: IConfig;
+    getConfig: () => IConfig;
+    setConfig: (key: string, value: any) => Promise<void>;
+    setUserInfo: (key: string, value: any) => Promise<void>;
+    reset: () => void;
+    validate: () => boolean;
+    isLogin: () => boolean;
+    check(): boolean;
+}
+
+type CallStatusType = (typeof CallStatus)[keyof typeof CallStatus];
+declare class Connect {
+    callKit: CallKit;
+    /**
+     * connectStatus:  init registered connecting calling
+     */
+    connectStatus: number;
+    currentSession?: Invitation;
+    mediaStream?: MediaStream;
+    userAgent?: UserAgent;
+    registerer?: Registerer;
+    sipConnected: boolean;
+    /**
+     * Whether it's an outgoing call
+     */
+    isOutgoing: boolean;
+    /**
+     * Whether it's an active hangup
+     */
+    isUnprompted: boolean;
+    /**
+     * Whether registered
+     * @param
+     * @deprecated Deprecated, please use isRegistered method
+     */
+    get isRegister(): boolean;
+    /**
+     * Call hold
+     * @param isHold
+     */
+    isHold: boolean;
+    /**
+     * Whether muted
+     */
+    isMute: boolean;
+    constructor(callKit: CallKit);
+    reset(): void;
+    private getAduioReference;
+    permission(): Promise<void>;
+    isRegistered(): boolean;
+    /**
+     * Making connection
+     * @returns
+     */
+    isConnecting(): boolean;
+    /**
+     * In call
+     * @returns
+     */
+    isCalling(): boolean;
+    /**
+     * Ringing
+     */
+    isRinging(): boolean;
+    /**
+     *
+     */
+    isHolding(): boolean;
+    /**
+     * Call ended, call not started
+     * @returns
+     */
+    isInit(): boolean;
+    register(): Promise<void>;
+    unregister(): Promise<void>;
+    call(callback: Function): Promise<void>;
+    /**
+     * Update registration status
+     * @param register
+     */
+    setRegister(register: boolean): void;
+    /**
+     * Set call status
+     * @param status
+     */
+    setConnectStatus(status: CallStatusType): void;
+    /**
+     * Hang up
+     * @param isUnprompted Whether actively hanging up
+     * @param isError Whether an error occurred
+     * @returns
+     */
+    hangup(isUnprompted?: boolean, isError?: boolean): Promise<void>;
+    /**
+     * The remote media stream. Undefined if call not answered.
+     * @param session - Session to get the media stream from.
+     */
+    getRemoteMediaStream(session: any): any;
+    setupRemoteMedia(session: any): void;
+    /**
+     * Update hold
+     * @param hold
+     */
+    setHoldStatus(hold: boolean): void;
+    setHold(hold: boolean): Promise<void>;
+    hold(): Promise<void>;
+    unhold(): Promise<void>;
+    setMute(mute: boolean): Promise<void>;
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+}
+
+declare class User {
+    private callKit;
+    userStatus: number;
+    constructor(callKit: CallKit);
+    /**
+     *
+     * @param status logout(1, "unregistered"), idle(2, "free"), break(3, "nap"), busy(4, "busy")
+     */
+    setUserStatus(status: number): Promise<void>;
+    /**
+     * Update user status
+     * @param status
+     */
+    updateUserStatus(status: number): Promise<void>;
+}
+
+interface CallKitConfig {
+    host: string;
+    audioRef: HTMLAudioElement | (() => HTMLAudioElement);
+    socket: string;
+    constrains?: WebrtcConstranis;
+    log?: LoggerLevel;
+}
+type ConfigEntity = CallKitConfig & Partial<IConfig>;
+type kitEventType = (typeof KitEvent)[keyof typeof KitEvent];
+interface Listener {
+    event: kitEventType;
+    callback: (...args: any[]) => void;
+}
+declare class CallKit {
+    api: Api;
+    config: Config;
+    logger: Logger;
+    callCenter: Call;
+    connect: Connect;
+    socket: Socket;
+    user: User;
+    listener: Listener[];
+    constructor(options: ConfigEntity);
+    login(username: string, password: string, extra?: object): Promise<void>;
+    logout(): Promise<void>;
+    call(extno?: string | number): Promise<void>;
+    register(): Promise<void>;
+    unregister(): Promise<void>;
+    hangup(): Promise<void>;
+    hold(): void;
+    unhold(): void;
+    setFree(): Promise<void>;
+    setSleep(): Promise<void>;
+    setBusy(): Promise<void>;
+    reset(): Promise<void>;
+    on(event: kitEventType, callback: (...args: any[]) => void): void;
+    off(event: kitEventType, callback?: (...args: any[]) => void): void;
+    removeAllListeners(): void;
+    trigger(event: kitEventType, data?: any): void;
+}
+
+export { CallKit, CallKitConfig, ConfigEntity, kitEventType };