react-sip-kit 0.5.21 → 0.6.2

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,255 @@
-# 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)
+
+# 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** — automatic device detection  
+- 🎥 **Video Support** — manage local & remote streams seamlessly  
+- 🔴 **Call Recording** — audio/video recording built-in  
+- 🖥️ **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  
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-sip-kit
+# or
+yarn add react-sip-kit
+````
+
+---
+
+## 🚀 Getting Started
+
+### 1️⃣ Initialize a `SipManager`
+
+Create a single `SipManager` instance. Add accounts dynamically as needed.
+
+```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 = [
+    {
+      account: {
+        domain: 'sip.example.com',
+        username: '1010',
+        password: 'password',
+        wssServer: 'sip.example.com',
+        webSocketPort: '8089',
+        serverPath: '/ws',
+      },
+    },
+  ];
+
+  useEffect(() => {
+    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 & methods
+
+Fetch **methods** and **account state** via username, lineKey, or remoteNumber:
+
+```tsx
+// App.tsx
+import { SipConnection } from './main';
+
+function App({ username }: { username: string }) {
+  const { dialByNumber } = SipConnection.getSessionMethodsBy({ username });
+  const { watch, status, lines } = SipConnection.getAccountBy({ username });
+
+  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>
+    </>
+  );
+}
+```
+
+You can also use **lineKey** or **remoteNumber** instead of username:
+
+```ts
+SipConnection.getSessionMethodsBy({ lineKey: 1 });
+SipConnection.getAccountBy({ remoteNumber: '1001' });
+```
+
+---
+
+### 3️⃣ Watch session data (`useWatchSessionData`)
+
+Fine-grained updates for a line/session:
+
+```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>;
+}
+```
+
+Watch multiple fields:
+
+```tsx
+const [localMediaStatus, isRecording] = useWatchSessionData({
+  key: { lineKey: 1 },
+  name: ['localMediaStreamStatus', 'recordMedia.recording'],
+});
+```
+
+Works with `remoteNumber` as well:
+
+```tsx
+const isMuted = useWatchSessionData({
+  key: { remoteNumber: '1001' },
+  name: '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.
+
+```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' });
+```
+
+**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.
+
+---
+
+### 5️⃣ Render media streams
+
+Media components are line-bound:
+
+```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} />
+```
+
+---
+
+## ⚙️ Configuration
+
+Each SIP account supports account, media, and feature settings:
+
+```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
+
+* 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)`.
+
+---
+
+## 🧑‍💻 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
+* Call recording & screen sharing
+* Local & remote media rendering
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 👤 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)

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/constructors/line.d.ts

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

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

@@ -1,21 +1,81 @@
-import { SipSessionDataType } from '../../store/types';
+import { LineType, SipSessionDataType } from '../../store/types';
 type Primitive = string | number | boolean | symbol | null | undefined;
 type Path<T> = {
     [K in keyof T & string]: T[K] extends Primitive | Array<any> ? K : K | `${K}.${Path<T[K]>}`;
 }[keyof T & string];
 /** Resolve the value type of a dot-path string. */
 type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends string ? PathValue<T[K], Rest> : never : never : P extends keyof T ? T[P] : never;
-/** ---------- Hook overloads ---------- */
+/**
+ * React hook to watch SIP session data for a specific line.
+ *
+ * Provide a single `key` object containing **either** `lineKey` or `remoteNumber`.
+ * You can also optionally specify `name` to access a specific property (supports dot-paths),
+ * or an array of names to get multiple properties at once.
+ *
+ * @param {Object} params
+ * @param {Object} params.key - Lookup key for the line/session.
+ * @param {number} [params.key.lineKey] - Numeric line identifier. Takes priority if both keys are somehow provided.
+ * @param {string} [params.key.remoteNumber] - Remote number of the SIP session. Used if `lineKey` is not provided.
+ * @param {string | string[]} [params.name] - Optional dot-path string (e.g., 'localMediaStreamStatus.videoEnabled')
+ *                                            or array of dot-paths to select specific data from the session.
+ *
+ * @returns {SipSessionDataType | any | any[]}
+ * Returns the full session data if `name` is undefined,
+ * a single property if `name` is a string,
+ * or an array of properties if `name` is an array.
+ *
+ * @example
+ * // Watch full session data by lineKey
+ * const sessionData = useWatchSessionData({ key: { lineKey: 1 } });
+ *
+ * // Watch a specific property by lineKey
+ * const videoEnabled = useWatchSessionData({ key: { lineKey: 1 }, name: 'localMediaStreamStatus.videoEnabled' });
+ *
+ * // Watch full session data by remoteNumber
+ * const sessionData = useWatchSessionData({ key: { remoteNumber: '1001' } });
+ *
+ * // Watch multiple properties by remoteNumber
+ * const [videoEnabled, audioEnabled] = useWatchSessionData({
+ *   key: { remoteNumber: '1001' },
+ *   name: ['localMediaStreamStatus.videoEnabled', 'localMediaStreamStatus.audioEnabled']
+ * });
+ */
 export declare function useWatchSessionData(props: {
-    lineNumber: number;
+    key: {
+        lineKey: LineType['lineKey'];
+    };
     name?: undefined;
 }): SipSessionDataType;
+export declare function useWatchSessionData(props: {
+    key: {
+        remoteNumber: SipSessionDataType['remoteNumber'];
+    };
+    name?: undefined;
+}): SipSessionDataType;
+export declare function useWatchSessionData<P extends Path<SipSessionDataType>>(props: {
+    key: {
+        lineKey: LineType['lineKey'];
+    };
+    name: P;
+}): PathValue<SipSessionDataType, P>;
 export declare function useWatchSessionData<P extends Path<SipSessionDataType>>(props: {
-    lineNumber: number;
+    key: {
+        remoteNumber: SipSessionDataType['remoteNumber'];
+    };
     name: P;
 }): PathValue<SipSessionDataType, P>;
 export declare function useWatchSessionData<const P extends readonly Path<SipSessionDataType>[]>(props: {
-    lineNumber: number;
+    key: {
+        lineKey: LineType['lineKey'];
+    };
+    name: P;
+}): {
+    [K in keyof P]: PathValue<SipSessionDataType, P[K] & string>;
+};
+export declare function useWatchSessionData<const P extends readonly Path<SipSessionDataType>[]>(props: {
+    key: {
+        remoteNumber: SipSessionDataType['remoteNumber'];
+    };
     name: P;
 }): {
     [K in keyof P]: PathValue<SipSessionDataType, P[K] & string>;