react-sip-kit 0.6.2 → 0.7.0-beta

package/README.md

@@ -1,4 +1,3 @@
-
 # react-sip-kit
 
 A modern **React SIP.js toolkit** for building web softphones and SIP clients.  
@@ -8,14 +7,14 @@ Supports **audio/video calls**, **call recording**, **screen sharing**, and **de
 
 ## ✨ Features
 
-- 📞 **Audio & Video Calls** — automatic device detection  
-- 🎥 **Video Support** — manage local & remote streams seamlessly  
-- 🔴 **Call Recording** — audio/video recording built-in  
+- 📞 **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** — select audio/video input & output devices  
-- 🔄 **Multi-account & Multi-line Support** — handle multiple SIP accounts and concurrent calls  
-- ⚡ **TypeScript-first** — type-safe, modular APIs  
-- 🛠️ **Configurable & Extensible** — tailored to your SIP setup  
+- 🎧 **Device Management** — choose input/output devices  
+- 🔄 **Multi-Account & Multi-Line Support** — concurrent calls  
+- ⚡ **TypeScript-first API** — safe and clean  
+- 🛠️ **Configurable & Extensible**
 
 ---
 
@@ -29,11 +28,9 @@ yarn add react-sip-kit
 
 ---
 
-## 🚀 Getting Started
-
-### 1️⃣ Initialize a `SipManager`
+## 🚀 Quick Start
 
-Create a single `SipManager` instance. Add accounts dynamically as needed.
+### 1️⃣ Create a SipManager Instance
 
 ```tsx
 // main.tsx
@@ -47,6 +44,7 @@ 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',
@@ -60,13 +58,11 @@ const Providers = () => {
 
   useEffect(() => {
     configs.forEach((config) => SipConnection.add(config));
-  }, [configs]);
+  }, []);
 
   return (
     <StrictMode>
-      {configs.map((config) => (
-        <App key={config.account.username} username={config.account.username} />
-      ))}
+      <App />
     </StrictMode>
   );
 };
@@ -76,109 +72,71 @@ createRoot(document.getElementById('root')!).render(<Providers />);
 
 ---
 
-### 2️⃣ Access SIP state & methods
+## 🔑 Resolving Accounts & Sessions
 
-Fetch **methods** and **account state** via username, lineKey, or remoteNumber:
+All lookups use one of the following keys:
 
-```tsx
-// App.tsx
-import { SipConnection } from './main';
-
-function App({ username }: { username: string }) {
-  const { dialByNumber } = SipConnection.getSessionMethodsBy({ username });
-  const { watch, status, lines } = SipConnection.getAccountBy({ username });
+| 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' }` |
 
-  const account = 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>
-    </>
-  );
-}
-```
+### 2️⃣ Access Methods (Dial, Hold, Mute, etc.)
 
-You can also use **lineKey** or **remoteNumber** instead of username:
+```tsx
+// Using configKey
+const { dialByNumber } = SipConnection.getSessionMethodsBy({ configKey: 'support-01' });
+dialByNumber('audio', '1002');
 
-```ts
-SipConnection.getSessionMethodsBy({ lineKey: 1 });
-SipConnection.getAccountBy({ remoteNumber: '1001' });
+// Using lineKey (after a call is active)
+SipConnection.getSessionMethodsBy({ lineKey: 1 }).hold();
 ```
 
 ---
 
-### 3️⃣ Watch session data (`useWatchSessionData`)
-
-Fine-grained updates for a line/session:
+### 3️⃣ Read Account State (Reactive)
 
 ```tsx
-import { useWatchSessionData } from 'react-sip-kit';
-
-function RecordingStatus({ lineKey }: { lineKey: number }) {
-  const isRecording = useWatchSessionData({
-    key: { lineKey },
-    name: 'recordMedia.recording',
-  });
-
-  return <p>Recording: {isRecording ? 'Yes' : 'No'}</p>;
-}
+const { watch, status } = SipConnection.getAccountBy({ configKey: 'support-01' });
+const account = watch(); // contains lines, registration, media devices, etc.
 ```
 
-Watch multiple fields:
+---
+
+### 4️⃣ Track Session State (`useWatchSessionData`)
 
 ```tsx
-const [localMediaStatus, isRecording] = useWatchSessionData({
+import { useWatchSessionData } from 'react-sip-kit';
+
+const isRecording = useWatchSessionData({
   key: { lineKey: 1 },
-  name: ['localMediaStreamStatus', 'recordMedia.recording'],
+  name: 'recordMedia.recording',
 });
-```
 
-Works with `remoteNumber` as well:
-
-```tsx
-const isMuted = useWatchSessionData({
-  key: { remoteNumber: '1001' },
-  name: 'localMediaStreamStatus.muted',
+const [mediaStatus, isMuted] = useWatchSessionData({
+  key: { configKey: 'support-01', remoteNumber: '1002' },
+  name: ['localMediaStreamStatus', 'localMediaStreamStatus.muted'],
 });
 ```
----
 
-### 4️⃣ Helper Resolver Methods
+---
 
-`SipManager` provides convenient **resolver methods** for quickly looking up lines, sessions, or usernames by `lineKey` or `remoteNumber`. These help avoid manually mapping usernames or tracking lines.
+### 5️⃣ Resolver Helper Methods
 
 ```ts
-import { SipConnection } from './main';
-
-// Get a specific line
-const line = SipConnection.getLineBy({ lineKey: 1 });
-// or by remote number
-const remoteLine = SipConnection.getLineBy({ remoteNumber: '1001' });
-
-// Get an active SIP session
-const session = SipConnection.getSessionBy({ lineKey: 1 });
-// or by remote number
-const remoteSession = SipConnection.getSessionBy({ remoteNumber: '1001' });
-
-// Get the username for a line
-const username = SipConnection.getUsernameBy({ lineKey: 1 });
-// or by remote number
-const remoteUsername = SipConnection.getUsernameBy({ remoteNumber: '1001' });
-```
+SipConnection.getLineBy({ lineKey: 1 });
+SipConnection.getLineBy({ configKey: 'support-01', remoteNumber: '1002' });
 
-**Notes:**
-
-* These methods are **lookup helpers only** — they do not return reactive data.
-* Combine with `getAccountBy()` or `useWatchSessionData()` for reactive state.
-* Useful when you have only a `lineKey` or `remoteNumber` but need the username or session quickly.
+SipConnection.getSessionBy({ lineKey: 1 });
+SipConnection.getUsernameBy({ configKey: 'support-01', remoteNumber: '1002' });
+```
 
 ---
 
-### 5️⃣ Render media streams
-
-Media components are line-bound:
+### 6️⃣ Render Media Streams
 
 ```tsx
 import { VideoStream, AudioStream } from 'react-sip-kit';
@@ -191,12 +149,50 @@ import { VideoStream, AudioStream } from 'react-sip-kit';
 
 ---
 
-## ⚙️ Configuration
+### 🧠 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} />
+      ))}
+    </>
+  );
+};
+```
+
+---
 
-Each SIP account supports account, media, and feature settings:
+## ⚙️ Configuration Schema
 
 ```ts
 {
+  key?: string; // optional → falls back to account.username
   account: {
     domain: 'your.sip.domain',
     username: 'user',
@@ -205,38 +201,41 @@ Each SIP account supports account, media, and feature settings:
     webSocketPort: '8089',
     serverPath: '/ws',
   },
-  features: { enableVideo: true },
-  media: {
-    audioInputDeviceId: 'default',
-    audioOutputDeviceId: 'default',
-    videoInputDeviceId: 'default',
+  features?: { enableVideo?: boolean },
+  media?: {
+    audioInputDeviceId?: string;
+    audioOutputDeviceId?: string;
+    videoInputDeviceId?: string;
   },
-  registration: { registerExpires: 3600 },
+  registration?: { registerExpires?: number },
 }
 ```
 
 ---
 
-## 💡 Best Practices
+## ✅ Best Practices
 
-* Use `username`, `lineKey`, or `remoteNumber` to fetch methods/state.
-* `.watch()` provides reactive account data (`lines`, `status`).
-* `useWatchSessionData` tracks **line-specific updates** (mute, hold, video, recording, etc.).
-* Render `<VideoStream>` & `<AudioStream>` only for active calls.
-* Manage mic/camera permissions upfront.
-* Add accounts dynamically with `SipConnection.add(config)`.
+| 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
+## 📂 Examples
 
 Check [`/example`](https://github.com/shervin-ghajar/react-sip-kit/tree/main/example) for:
 
-* Multi-account setups
-* Audio & video calls
-* Hold, mute, attended transfer
+* Multi-account softphone
+* Audio/video calls
+* Hold / mute / attended transfer
 * Call recording & screen sharing
-* Local & remote media rendering
+* Stream rendering
 
 ---
 
@@ -250,6 +249,6 @@ MIT
 
 **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)
+* 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/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,11 +1,12 @@
-import { SipAccountConfig } from '../configs/types';
+import { SipAccountConfig, SipConfigs } from '../configs/types';
 import { LineType, SipInvitationType } from '../store/types';
 export declare class Line implements LineType {
-    lineKey: number;
+    configKey: SipConfigs['key'];
+    lineKey: LineType['lineKey'];
     remoteNumber: string;
     username: string;
     sipSession: SipInvitationType | null;
     localSoundMeter: any;
     remoteSoundMeter: any;
-    constructor(username: SipAccountConfig['username'], lineKey: number, remoteNumber: 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>;

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

@@ -1,6 +1,6 @@
-import { SipAccountConfig } from '../../configs/types';
+import { SipConfigs } from '../../configs/types';
 import { SipUserAgent } from '../../types';
-export declare function onTransportConnected(username: SipAccountConfig['username'], userAgent?: SipUserAgent | null): void;
-export declare function onTransportConnectError(error: Error, username: SipAccountConfig['username'], userAgent?: SipUserAgent | null): void;
-export declare function onTransportDisconnected(username: SipAccountConfig['username'], userAgent: SipUserAgent): void;
-export declare function reconnectTransport(username: SipAccountConfig['username'], userAgent?: SipUserAgent | null): void;
+export declare function onTransportConnected(configKey: SipConfigs['key'], userAgent?: SipUserAgent | null): void;
+export declare function onTransportConnectError(error: Error, configKey: SipConfigs['key'], userAgent?: SipUserAgent | null): void;
+export declare function onTransportDisconnected(configKey: SipConfigs['key'], userAgent: SipUserAgent): void;
+export declare function reconnectTransport(configKey: SipConfigs['key'], userAgent?: SipUserAgent | null, forceReconnect?: boolean): void;

package/dist/hooks/useSipManager/index.d.ts

@@ -1,7 +1,7 @@
-import { SipAccountConfig } from '../../configs/types';
+import { SipConfigs } from '../../configs/types';
 import { LineType } from '../../store/types';
-export declare function useSipManager({ username }: {
-    username: SipAccountConfig['username'];
+export declare function useSipManager({ configKey }: {
+    configKey: SipConfigs['key'];
 }): () => {
     status: import("../../store/types").SipUserAgentStatus;
     lines: LineType[];

package/dist/hooks/useWatchConfigs/index.d.ts

@@ -0,0 +1 @@
+export declare const useWatchConfigs: () => import("../../configs/types").SipConfigs[];

package/dist/hooks/useWatchSessionData/index.d.ts

@@ -1,3 +1,4 @@
+import { SipConfigs } from '../../configs/types';
 import { LineType, SipSessionDataType } from '../../store/types';
 type Primitive = string | number | boolean | symbol | null | undefined;
 type Path<T> = {
@@ -49,6 +50,7 @@ export declare function useWatchSessionData(props: {
 export declare function useWatchSessionData(props: {
     key: {
         remoteNumber: SipSessionDataType['remoteNumber'];
+        configKey: SipConfigs['key'];
     };
     name?: undefined;
 }): SipSessionDataType;
@@ -61,6 +63,7 @@ export declare function useWatchSessionData<P extends Path<SipSessionDataType>>(
 export declare function useWatchSessionData<P extends Path<SipSessionDataType>>(props: {
     key: {
         remoteNumber: SipSessionDataType['remoteNumber'];
+        configKey: SipConfigs['key'];
     };
     name: P;
 }): PathValue<SipSessionDataType, P>;
@@ -75,6 +78,7 @@ export declare function useWatchSessionData<const P extends readonly Path<SipSes
 export declare function useWatchSessionData<const P extends readonly Path<SipSessionDataType>[]>(props: {
     key: {
         remoteNumber: SipSessionDataType['remoteNumber'];
+        configKey: SipConfigs['key'];
     };
     name: P;
 }): {