react-sip-kit 0.5.21 → 0.7.0-beta

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Shervin Ghajar
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Shervin Ghajar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,212 +1,254 @@
-# react-sip-kit
-
-A modern **React SIP.js toolkit** for building web-based softphones and SIP clients.
-Supports **audio/video calls**, **recording**, **screen sharing**, and **device management** — all with a clean, extensible architecture.
-
----
-
-## ✨ Features
-
-* 📞 **Audio & Video Calls** — with automatic device detection
-* 🎥 **Video Support** — manage local & remote streams seamlessly
-* 🔴 **Call Recording** — audio and video recording out of the box
-* 🖥️ **Screen Sharing** — during video calls
-* 🎧 **Device Management** — select audio/video input & output devices
-* 🔄 **Multi-account & Multi-line Support** — handle multiple SIP accounts and concurrent calls
-* ⚡ **TypeScript-first** — fast, modular, type-safe APIs
-* 🛠️ **Configurable & Extensible** — tailor to your SIP setup
-
----
-
-## 📦 Installation
-
-```bash
-npm install react-sip-kit
-# or
-yarn add react-sip-kit
-```
-
----
-
-## 🚀 Basic Usage
-
-### 1. Initialize a global `SipManager`
-
-Instead of wrapping your app with a provider, you now create a single `SipManager` instance and add accounts dynamically.
-
-```tsx
-// main.ts
-import App from './App';
-import { SipManager } from 'react-sip-kit';
-import { StrictMode, useEffect, useState } from 'react';
-import { createRoot } from 'react-dom/client';
-------------------------------------------------------------
-export const SipConnection = new SipManager(); // Initilizing SipManager
-------------------------------------------------------------
-const Providers = () => {
-  const configs = [{
-    account: {
-      domain: 'sip.example.com',
-      username: '1010',
-      password: 'password',
-      wssServer: 'sip.example.com',
-      webSocketPort: '8089',
-      serverPath: '/ws',
-    },
-    // ...(other configs)
-  }]
-
-  useEffect(() => {
-    // Add new configs dynamically
-    configs.forEach((config) => {
-      SipConnection.add(config);
-    });
-  }, [configs]);
-
-  return (
-    <StrictMode>
-      {configs.map((config) => (
-        <App key={config.account.username} username={config.account.username} />
-      ))}
-    </StrictMode>
-  );
-};
-
-createRoot(document.getElementById('root')!).render(<Providers />);
-```
-
----
-
-### 2. Access SIP state and methods (per account)
-
-Each account is keyed by its **username**.
-You can fetch **methods** and **watch state** like this:
-
-```tsx
-// App.tsx
-import { SipConnection } from './main';
-
-function App({ username }: { username: string }) {
-  const { dialByNumber } = SipConnection.methods(username);
-  const { watch } = SipConnection.get(username);
-  const { lines, status } = watch();
-
-  return (
-    <>
-      <h2>
-        Web Phone {username} — {status}
-      </h2>
-      <button onClick={() => dialByNumber('audio', '1012')}>Call 1012</button>
-      <button onClick={() => dialByNumber('video', '1012')}>Video Call 1012</button>
-    </>
-  );
-}
-```
-
----
-
-### 3. Watch line/session data with `useWatchSessionData`
-
-For fine-grained updates, subscribe to session fields:
-
-```tsx
-import { useWatchSessionData } from 'react-sip-kit';
-
-function RecordingStatus({ lineNumber }: { lineNumber: number }) {
-  const isRecording = useWatchSessionData({
-    lineNumber,
-    name: 'recordMedia.recording',
-  });
-
-  return <p>Recording: {isRecording ? 'Yes' : 'No'}</p>;
-}
-```
-
-You can also watch multiple fields:
-
-```tsx
-const [localMediaStreamStatus, isRecording] = useWatchSessionData({
-  lineNumber: 1,
-  name: ['localMediaStreamStatus', 'recordMedia.recording'],
-});
-```
-
----
-
-### 4. Render media streams
-
-Media components (`<Video/>` & `<Audio/>`) are bound per line:
-
-```tsx
-import { VideoStream, AudioStream } from 'react-sip-kit';
-
-<VideoStream type="local" lineNumber={1} />
-<VideoStream type="remote" lineNumber={1} />
-<AudioStream type="local" lineNumber={1} />
-<AudioStream type="remote" lineNumber={1} />
-```
-
----
-
-## ⚙️ Configuration
-
-Each account supports SIP and media options:
-
-```ts
-{
-  account: {
-    domain: 'your.sip.domain',
-    username: 'user',
-    password: 'secret',
-    wssServer: 'your.sip.domain',
-    webSocketPort: '8089',
-    serverPath: '/ws',
-  },
-  features: { enableVideo: true },
-  media: {
-    audioInputDeviceId: 'default',
-    audioOutputDeviceId: 'default',
-    videoInputDeviceId: 'default',
-  },
-  registration: { registerExpires: 3600 },
-}
-```
-
----
-
-## 💡 Best Practices
-
-* Always pass the `username` when calling `SipConnection.methods(username)` or `SipConnection.get(username)`.
-* Use `.watch()` for reactive state (`lines`, `status`).
-* Use `useWatchSessionData` for **line-specific** updates (mute, hold, video state, recording, etc.).
-* Render `<VideoStream>` and `<AudioStream>` **only for active calls**.
-* Manage device permissions (mic/camera) upfront.
-* If adding accounts dynamically, call `SipConnection.add(config)` for each.
-
----
-
-## 🧑‍💻 Full Example
-
-See the [`/example`](https://github.com/shervin-ghajar/react-sip-kit/tree/main/example) folder for:
-
-* Multiple SIP accounts in one UI
-* Audio & video calls
-* Hold, mute, attended transfer
-* Call recording & screen sharing
-* Local & remote media rendering
-
----
-
-## 📄 License
-
-MIT License
-
----
-
-## 👤 Author
-
-**Shervin Ghajar**
-
-* GitHub: [@shervin-ghajar](https://github.com/shervin-ghajar)
-* NPM: [react-sip-kit](https://www.npmjs.com/package/react-sip-kit)
-* Repository: [react-sip-kit](https://github.com/shervin-ghajar/react-sip-kit)
+# react-sip-kit
+
+A modern **React SIP.js toolkit** for building web softphones and SIP clients.  
+Supports **audio/video calls**, **call recording**, **screen sharing**, and **device management**, all with a clean, extensible, TypeScript-first architecture.
+
+---
+
+## ✨ Features
+
+- 📞 **Audio & Video Calls** — with device auto-detection  
+- 🎥 **Video Support** — render local & remote streams easily  
+- 🔴 **Call Recording** — audio/video capture  
+- 🖥️ **Screen Sharing** — during video calls  
+- 🎧 **Device Management** — choose input/output devices  
+- 🔄 **Multi-Account & Multi-Line Support** — concurrent calls  
+- ⚡ **TypeScript-first API** — safe and clean  
+- 🛠️ **Configurable & Extensible**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-sip-kit
+# or
+yarn add react-sip-kit
+````
+
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Create a SipManager Instance
+
+```tsx
+// main.tsx
+import App from './App';
+import { SipManager } from 'react-sip-kit';
+import { StrictMode, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+
+export const SipConnection = new SipManager();
+
+const Providers = () => {
+  const configs = [
+    {
+      key: 'support-01', // Optional → If omitted, defaults to account.username
+      account: {
+        domain: 'sip.example.com',
+        username: '1010',
+        password: 'password',
+        wssServer: 'sip.example.com',
+        webSocketPort: '8089',
+        serverPath: '/ws',
+      },
+    },
+  ];
+
+  useEffect(() => {
+    configs.forEach((config) => SipConnection.add(config));
+  }, []);
+
+  return (
+    <StrictMode>
+      <App />
+    </StrictMode>
+  );
+};
+
+createRoot(document.getElementById('root')!).render(<Providers />);
+```
+
+---
+
+## 🔑 Resolving Accounts & Sessions
+
+All lookups use one of the following keys:
+
+| Key            | Purpose                                                       | Example                                             |
+| -------------- | ------------------------------------------------------------- | --------------------------------------------------- |
+| `configKey`    | Refers to a specific SIP account instance                     | `{ configKey: 'support-01' }`                       |
+| `lineKey`      | Refers to an **active call** / line                           | `{ lineKey: 1 }`                                    |
+| `remoteNumber` | Refers to peer phone number — must be paired with `configKey` | `{ configKey: 'support-01', remoteNumber: '1001' }` |
+
+---
+
+### 2️⃣ Access Methods (Dial, Hold, Mute, etc.)
+
+```tsx
+// Using configKey
+const { dialByNumber } = SipConnection.getSessionMethodsBy({ configKey: 'support-01' });
+dialByNumber('audio', '1002');
+
+// Using lineKey (after a call is active)
+SipConnection.getSessionMethodsBy({ lineKey: 1 }).hold();
+```
+
+---
+
+### 3️⃣ Read Account State (Reactive)
+
+```tsx
+const { watch, status } = SipConnection.getAccountBy({ configKey: 'support-01' });
+const account = watch(); // contains lines, registration, media devices, etc.
+```
+
+---
+
+### 4️⃣ Track Session State (`useWatchSessionData`)
+
+```tsx
+import { useWatchSessionData } from 'react-sip-kit';
+
+const isRecording = useWatchSessionData({
+  key: { lineKey: 1 },
+  name: 'recordMedia.recording',
+});
+
+const [mediaStatus, isMuted] = useWatchSessionData({
+  key: { configKey: 'support-01', remoteNumber: '1002' },
+  name: ['localMediaStreamStatus', 'localMediaStreamStatus.muted'],
+});
+```
+
+---
+
+### 5️⃣ Resolver Helper Methods
+
+```ts
+SipConnection.getLineBy({ lineKey: 1 });
+SipConnection.getLineBy({ configKey: 'support-01', remoteNumber: '1002' });
+
+SipConnection.getSessionBy({ lineKey: 1 });
+SipConnection.getUsernameBy({ configKey: 'support-01', remoteNumber: '1002' });
+```
+
+---
+
+### 6️⃣ Render Media Streams
+
+```tsx
+import { VideoStream, AudioStream } from 'react-sip-kit';
+
+<VideoStream type="local" lineKey={1} />
+<VideoStream type="remote" lineKey={1} />
+<AudioStream type="local" lineKey={1} />
+<AudioStream type="remote" lineKey={1} />
+```
+
+---
+
+### 🧠 Managing Config Keys & Dynamic Rendering
+
+```tsx
+const configs = SipConnection.useWatchConfigs();
+// → [{ key: 'support-01', account: {...} }, { key: 'sales-02', ... }]
+```
+
+✅ **When to use `useWatchConfigs()`**
+
+| Scenario                                               | Should you use it?      | Reason                                                                          |
+| ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------- |
+| Static single account                                  | ❌ Not required          | `configKey` is constant                                                         |
+| You manually track configs in your own state           | ❌ Optional              | You already control the list                                                    |
+| **Rendering UI for *each* config account dynamically** | ✅ **Yes — recommended** | Ensures you always use the correct `configKey`, even if keys are auto-generated |
+| **Configs can be added or removed at runtime**         | ✅ **Always**            | Prevents mismatched lookups or stale references                                 |
+
+> **✔ Best Practice:**
+> Always call `useWatchConfigs()` when rendering **lists of lines or accounts**, to ensure that each component receives the correct and *current* `configKey`.
+
+---
+
+Example (Rendering a phone UI for *every* config dynamically):
+
+```tsx
+const AccountsUI = () => {
+  const configs = SipConnection.useWatchConfigs();
+
+  return (
+    <>
+      {configs.map((config) => (
+        <Lines key={config.key} configKey={config.key} />
+      ))}
+    </>
+  );
+};
+```
+
+---
+
+## ⚙️ Configuration Schema
+
+```ts
+{
+  key?: string; // optional → falls back to account.username
+  account: {
+    domain: 'your.sip.domain',
+    username: 'user',
+    password: 'secret',
+    wssServer: 'your.sip.domain',
+    webSocketPort: '8089',
+    serverPath: '/ws',
+  },
+  features?: { enableVideo?: boolean },
+  media?: {
+    audioInputDeviceId?: string;
+    audioOutputDeviceId?: string;
+    videoInputDeviceId?: string;
+  },
+  registration?: { registerExpires?: number },
+}
+```
+
+---
+
+## ✅ Best Practices
+
+| Task                   | Recommended Approach              |
+| ---------------------- | --------------------------------- |
+| Reference active call  | Use `lineKey` when available      |
+| Reference account      | Use `configKey`                   |
+| Lookup by phone number | Use `{ configKey, remoteNumber }` |
+| Track config keys      | Use `useWatchConfigs()`           |
+| Watch configs state    | `useWatchConfigs()`               |
+| Watch account state    | `getAccountBy().watch()`          |
+| Watch session props    | `useWatchSessionData()`           |
+
+---
+
+## 📂 Examples
+
+Check [`/example`](https://github.com/shervin-ghajar/react-sip-kit/tree/main/example) for:
+
+* Multi-account softphone
+* Audio/video calls
+* Hold / mute / attended transfer
+* Call recording & screen sharing
+* Stream rendering
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 👤 Author
+
+**Shervin Ghajar**
+
+* GitHub: [https://github.com/shervin-ghajar](https://github.com/shervin-ghajar)
+* NPM: [https://www.npmjs.com/package/react-sip-kit](https://www.npmjs.com/package/react-sip-kit)
+* Repository: [https://github.com/shervin-ghajar/react-sip-kit](https://github.com/shervin-ghajar/react-sip-kit)

package/dist/components/audio/index.d.ts

@@ -1,6 +1,6 @@
 import { AudioHTMLAttributes, HTMLAttributes } from 'react';
 interface DefaultAudioProps {
-    lineNumber: string | number;
+    lineKey: string | number;
 }
 interface LocalAudioProps extends AudioHTMLAttributes<HTMLAudioElement>, DefaultAudioProps {
     type: 'local';
@@ -11,5 +11,5 @@ interface RemoteAudioProps extends HTMLAttributes<HTMLDivElement>, DefaultAudioP
     id?: `line-${number}-remoteAudios`;
 }
 type AudioProps = LocalAudioProps | RemoteAudioProps;
-export declare const Audio: ({ lineNumber, ...rest }: AudioProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Audio: ({ lineKey, ...rest }: AudioProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/video/index.d.ts

@@ -1,6 +1,6 @@
 import { HTMLAttributes, VideoHTMLAttributes } from 'react';
 interface DefaultVideoProps {
-    lineNumber: string | number;
+    lineKey: string | number;
 }
 interface LocalVideoProps extends VideoHTMLAttributes<HTMLVideoElement>, DefaultVideoProps {
     type: 'local';
@@ -11,5 +11,5 @@ interface RemoteVidepProps extends HTMLAttributes<HTMLDivElement>, DefaultVideoP
     id?: `line-${number}-${RemoteVidepProps['type']}Video` | `line-${number}-remoteVideos`;
 }
 type VideoProps = LocalVideoProps | RemoteVidepProps;
-export declare const Video: ({ lineNumber, ...rest }: VideoProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Video: ({ lineKey, ...rest }: VideoProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/configs/index.d.ts

@@ -1,4 +1,4 @@
-import { SipAccountConfig, SipAdvancedConfig, SipConfigs, SipFeaturesConfig, SipMediaConfig, SipPermissionsConfig, SipPolicyConfig, SipRecordingConfig, SipRegistrationConfig, SipStorageConfig, SipXmppConfig } from './types';
+import { SipAccountConfig, SipAdvancedConfig, SipConfigs, SipFeaturesConfig, SipMediaConfig, SipPolicyConfig, SipRecordingConfig, SipRegistrationConfig, SipStorageConfig } from './types';
 export declare const defaultAccountConfig: SipAccountConfig;
 export declare const defaultFeaturesConfig: SipFeaturesConfig;
 export declare const defaultMediaConfig: SipMediaConfig;
@@ -7,6 +7,4 @@ export declare const defaultRegistrationConfig: SipRegistrationConfig;
 export declare const defaultStorageConfig: SipStorageConfig;
 export declare const defaultRecordingConfig: SipRecordingConfig;
 export declare const defaultAdvancedConfig: SipAdvancedConfig;
-export declare const defaultXmppConfig: SipXmppConfig;
-export declare const defaultPermissionsConfig: SipPermissionsConfig;
 export declare const defaultSipConfigs: SipConfigs;

package/dist/configs/types.d.ts

@@ -1,4 +1,5 @@
 export interface SipConfigs {
+    key: string;
     account: SipAccountConfig;
     features: SipFeaturesConfig;
     media: SipMediaConfig;
@@ -7,17 +8,6 @@ export interface SipConfigs {
     storage: SipStorageConfig;
     recording: SipRecordingConfig;
     advanced: SipAdvancedConfig;
-    xmpp: SipXmppConfig;
-    permissions: SipPermissionsConfig;
-}
-export interface SipPermissionsConfig {
-    enableSendFiles: boolean;
-    enableSendImages: boolean;
-    enableAudioRecording: boolean;
-    enableVideoRecording: boolean;
-    enableSms: boolean;
-    enableFax: boolean;
-    enableEmail: boolean;
 }
 export interface SipXmppConfig {
     server: string;
@@ -90,16 +80,8 @@ export interface SipMediaConfig {
 }
 export interface SipFeaturesConfig {
     enableVideo: boolean;
-    enableRingtone: boolean;
-    enableTextMessaging: boolean;
     enableTransfer: boolean;
     enableConference: boolean;
-    enableTextExpressions: boolean;
-    enableTextDictate: boolean;
-    enableAlphanumericDial: boolean;
-    enableAccountSettings: boolean;
-    enableAppearanceSettings: boolean;
-    enableNotificationSettings: boolean;
 }
 export interface SipAccountConfig {
     username: string;

package/dist/constructors/line.d.ts

@@ -1,9 +1,12 @@
+import { SipAccountConfig, SipConfigs } from '../configs/types';
 import { LineType, SipInvitationType } from '../store/types';
 export declare class Line implements LineType {
-    lineNumber: number;
-    displayNumber: string;
+    configKey: SipConfigs['key'];
+    lineKey: LineType['lineKey'];
+    remoteNumber: string;
+    username: string;
     sipSession: SipInvitationType | null;
     localSoundMeter: any;
     remoteSoundMeter: any;
-    constructor(lineNumber: number, displayNumber: string);
+    constructor(configKey: SipConfigs['key'], username: SipAccountConfig['username'], lineKey: LineType['lineKey'], remoteNumber: string);
 }

package/dist/events/registration/index.d.ts

@@ -1,16 +1,16 @@
-import { SipAccountConfig } from '../../configs/types';
+import { SipConfigs } from '../../configs/types';
 import { SipUserAgent } from '../../types';
 /**
  * Called when account is registered
  */
-export declare function onRegistered(username: SipAccountConfig['username'], userAgent: SipUserAgent): void;
+export declare function onRegistered(configKey: SipConfigs['key'], userAgent: SipUserAgent): void;
 /**
  * Called if UserAgent can connect, but not register.
  * @param {string} response Incoming request message
  * @param {string} cause Cause message. Unused
  **/
-export declare function onRegisterFailed(username: SipAccountConfig['username'], response: any, cause: any): void;
+export declare function onRegisterFailed(configKey: SipConfigs['key'], response: any, cause: any): void;
 /**
  * Called when Unregister is requested
  */
-export declare function onUnregistered(username: SipAccountConfig['username'], userAgent: SipUserAgent): void;
+export declare function onUnregistered(configKey: SipConfigs['key'], userAgent: SipUserAgent): void;

package/dist/events/session/index.d.ts

@@ -1,10 +1,10 @@
-import { SipAccountConfig } from '../../configs/types';
+import { SipConfigs } from '../../configs/types';
 import { LineType, SipSessionDescriptionHandler, SipSessionType } from '../../store/types';
 import { CallbackFunction } from '../../types';
 import { Bye, Message } from 'sip.js';
 import { IncomingRequestMessage, IncomingResponse } from 'sip.js/lib/core';
-export declare const sessionEvents: ({ username }: {
-    username: SipAccountConfig["username"];
+export declare const sessionEvents: ({ configKey }: {
+    configKey: SipConfigs["key"];
 }) => {
     onInviteCancel: (lineObj: LineType, response: IncomingRequestMessage, callback?: CallbackFunction<any>) => void;
     onInviteAccepted: (lineObj: LineType, videoEnabled: boolean, response?: IncomingResponse) => Promise<void>;