voxnix 1.0.0 → 1.0.2

package/README.md

@@ -1,10 +1,10 @@
-# Voxnix Plugin
+# Voxnix
 
-A self-contained Voice Widget Plugin running inside an iframe, built with React, Vite, and Tailwind CSS.
+A React Component SDK for seamless Voice PABX Integration.
 
 ## Overview
 
-This widget is designed to be embedded within a parent application (e.g., `wrapper-main`). All WebRTC logic (Yeastar, Flashphoner, Sip.js) runs inside the widget's memory. The parent application only needs to send configuration and credentials via `postMessage`.
+Voxnix is a ready-to-use SDK designed to quickly integrate voice and PABX calling features into your React applications. It provides a self-contained dialer UI and automatically handles voice engine connectivity, including remote media stream attachment and cleanup for Sip.js.
 
 ## Installation
 
@@ -16,86 +16,96 @@ yarn add voxnix
 
 ## Usage
 
-### 1. Embedding the Widget
-
-Embed the widget using an iframe in your React parent application. The communication protocol uses `window.postMessage`.
+You can use the `Voxnix` component directly in your React application. Pass the required PABX configuration credentials through the `config` prop and use the event callbacks to listen for call states. You can also use a React `ref` to imperatively control the call (e.g., answer, hold, mute, hangup) from your parent component.
 
 ```jsx
-import React, { useEffect, useRef } from 'react';
-
-const ParentApp = () => {
-  const widgetRef = useRef(null);
-
-  useEffect(() => {
-    const handleMessage = (event) => {
-      // 1. Wait for widget_ready event
-      if (event.data?.type === 'widget_ready') {
-        // 2. Send configuration to initialize the widget
-        widgetRef.current.contentWindow.postMessage({
-          type: 'init_config',
-          payload: {
-             tenantName: "Infomedia",
-             platform: "sipjs", // Options: "yeastar", "flashphoner", "sipjs"
-             pabxConfig: {
-               auth: {
-                 username: "YOUR_USERNAME",
-                 password: "YOUR_PASSWORD",
-                 host: "YOUR_PABX_HOST"
-               }
-             }
-          }
-        }, '*'); // Replace '*' with target origin in production for security
-      }
-
-      // Handle call events from widget to parent
-      if (event.data?.type === 'sync_incoming_call') {
-        console.log('Incoming call notification');
-      }
-      if (event.data?.type === 'sync_call_answered') {
-        console.log('Call answered');
-      }
-      if (event.data?.type === 'sync_call_ended') {
-        console.log('Call ended');
-      }
-    };
-
-    window.addEventListener('message', handleMessage);
-    return () => window.removeEventListener('message', handleMessage);
-  }, []);
+import React, { useRef } from 'react';
+import { Voxnix } from 'voxnix';
+
+const App = () => {
+  const voxnixRef = useRef(null);
+
+  const pabxConfig = {
+    auth: {
+      username: "YOUR_USERNAME",
+      password: "YOUR_PASSWORD",
+      host: "YOUR_PABX_HOST" // e.g., sip.example.com
+    }
+  };
+
+  const handleIncomingCall = (callData) => {
+    console.log('Incoming call notification:', callData);
+    // You can answer programmatically
+    // voxnixRef.current.answer();
+  };
+
+  const handleCallAnswered = () => {
+    console.log('Call has been answered');
+  };
+
+  const handleCallEnded = () => {
+    console.log('Call has ended');
+  };
+
+  const handleRegisterStatus = (status) => {
+    console.log('PABX Registration Status:', status); // "REGISTERED" | "FAILED"
+  };
+
+  // Example Call Controls
+  const toggleMute = (isMuted) => voxnixRef.current?.mute(isMuted);
+  const toggleHold = (isOnHold, setIsOnHold) => voxnixRef.current?.hold(isOnHold, setIsOnHold);
+  const endCall = () => voxnixRef.current?.hangup();
 
   return (
-    <iframe
-      src="http://localhost:5173" // Or your deployed widget URL
-      ref={widgetRef}
-      style={{ width: '400px', height: '600px', border: 'none', borderRadius: '8px' }}
-      allow="microphone; camera"
-    />
+    <div style={{ padding: '20px' }}>
+      <h1>Voice Integration App</h1>
+      
+      {/* Voxnix Voice Engine & UI Component */}
+      <Voxnix 
+        ref={voxnixRef}
+        config={pabxConfig}
+        onIncomingCall={handleIncomingCall}
+        onCallAnswered={handleCallAnswered}
+        onCallEnded={handleCallEnded}
+        onRegisterStatus={handleRegisterStatus}
+      />
+    </div>
   );
 };
 
-export default ParentApp;
+export default App;
 ```
 
-## Supported Voice Platforms
+## Component Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `Object` | Configuration object containing `auth` credentials (`username`, `password`, `host`). |
+| `onIncomingCall` | `Function` | Callback triggered when there is an incoming call. |
+| `onCallAnswered` | `Function` | Callback triggered when the call is answered. |
+| `onCallEnded` | `Function` | Callback triggered when the call ends. |
+| `onCallUnanswered` | `Function` | Callback triggered when an incoming call is not answered. |
+| `onRegisterStatus` | `Function` | Callback triggered when the PABX registration status changes. |
+
+## Ref API (Call Controls)
 
-- **Sip.js**
-- **Yeastar**
-- **Flashphoner**
+You can access these methods by passing a `ref` to the `Voxnix` component:
 
-## Message Events Protocol
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `answer()` | - | Answers an incoming call. |
+| `reject()` | - | Rejects an incoming call. |
+| `hangup()` | - | Ends the current active call. |
+| `mute(isMuted)` | `isMuted: boolean` | Mutes or unmutes the local microphone. |
+| `hold(isOnHold, setIsOnHold)` | `isOnHold: boolean, setIsOnHold: function` | Puts the call on hold or resumes it. Passes `setIsOnHold` to allow the SDK to asynchronously update the parent UI state when the re-INVITE succeeds. |
 
-### Parent -> Widget
-- `init_config`: Sent from parent to widget. Contains credentials (`tenantName`, `platform`, `pabxConfig: { auth: { username, password, host } }`).
+## Media Handling (Sip.js)
 
-### Widget -> Parent
-- `widget_ready`: Emitted when the React lifecycle of the widget is mounted, requesting `init_config` from the parent.
-- `sync_incoming_call`: Emitted to the parent when there is an incoming call (for desktop/native notifications).
-- `sync_call_answered`: Emitted when the call is answered.
-- `sync_call_ended`: Emitted when the call ends.
+Voxnix handles remote media setup automatically. When a call state becomes `Established`, Voxnix will attach the incoming audio stream to an invisible `<audio id="voxnix-remote-audio" />` element. When the call is terminated, the media is safely cleaned up.
 
 ## Development
 
-To start the widget locally:
+To run the project locally for development:
 
 ```bash
 yarn install