@dora-cell/sdk 0.1.1-beta.26 → 0.1.1-beta.30

package/README.md

@@ -8,9 +8,9 @@ VoIP calling SDK for Dora Cell - Make calls from any JavaScript application with
 ✅ **TypeScript support** - Full type definitions included  
 ✅ **WebRTC-based** - High-quality voice calls using JsSIP  
 ✅ **Event-driven API** - Listen to call state changes  
-✅ **API token authentication** - Secure, no user login required  
+✅ **Multiple Auth Modes** - Support for API Token and Direct Extension login  
 ✅ **Auto-extension selection** - Automatically selects first available extension  
-✅ **React bindings** - Optional React hooks for easy integration  
+✅ **React bindings** - Optional React hooks for easy integration
 
 ## Installation
 
@@ -22,110 +22,68 @@ yarn add @dora-cell/sdk jssip
 pnpm add @dora-cell/sdk jssip
 ```
 
-For React projects:
-```bash
-npm install @dora-cell/sdk @dora-cell/sdk-react jssip
-```
-
 ## Quick Start
 
-### Vanilla JavaScript
+### 1. Initialize the SDK
+
+Choose your preferred authentication method:
+
+#### Option A: Extension Authentication (Recommended for Testing)
+
+Best for quick testing or internal apps where default credentials are used.
 
 ```javascript
-import { DoraCell } from '@dora-cell/sdk';
+import { DoraCell } from "@dora-cell/sdk";
 
-// Initialize SDK with API token
 const sdk = new DoraCell({
   auth: {
-    type: 'api-token',
-    apiToken: 'your-api-token-here',
-    apiBaseUrl: 'https://api.usedora.com'
+    type: "extension",
+    extension: "1001",
   },
-  debug: true // Enable console logging
 });
+```
 
-// Initialize connection
-await sdk.initialize();
+#### Option B: API Token Authentication (Production)
 
-// Listen for connection status
-sdk.on('connection:status', (state) => {
-  console.log('Connection status:', state.status);
-});
+Securely fetch credentials from your backend.
 
-// Listen for call events
-sdk.on('call:connected', (call) => {
-  console.log('Call connected:', call.remoteNumber);
+```javascript
+const sdk = new DoraCell({
+  auth: {
+    type: "api-token",
+    apiToken: "your-api-token-here",
+    apiBaseUrl: "https://api.yourdomain.com",
+  },
 });
+```
+
+### 2. Connect and Register
 
-sdk.on('call:ended', (call, reason) => {
-  console.log('Call ended:', reason);
+```javascript
+// Listen for registration
+sdk.on("connection:status", (state) => {
+  if (state.status === "registered") {
+    console.log("SIP Ready to make calls!");
+  }
 });
 
-// Make a call
-const call = await sdk.call('+2348012345678');
+// Initialize connection
+await sdk.initialize();
+```
 
-// Mute/unmute
-call.mute();
-call.unmute();
+### 3. Make a Call
 
-// Hang up
-call.hangup();
-```
+```javascript
+try {
+  const call = await sdk.call("+2348012345678");
 
-### React
-
-```tsx
-import { DoraCellProvider, useCall, useConnectionStatus } from '@dora-cell/sdk-react';
-
-function App() {
-  return (
-    <DoraCellProvider
-      config={{
-        auth: {
-          type: 'api-token',
-          apiToken: 'your-api-token-here',
-          apiBaseUrl: 'https://api.usedora.com'
-        }
-      }}
-    >
-      <CallInterface />
-    </DoraCellProvider>
-  );
-}
+  // Mute/unmute
+  call.mute();
 
-function CallInterface() {
-  const { call, hangup, toggleMute, callStatus, callDuration, isMuted } = useCall();
-  const { isConnected } = useConnectionStatus();
-  const [number, setNumber] = useState('');
-
-  const handleCall = async () => {
-    try {
-      await call(number);
-    } catch (error) {
-      console.error('Call failed:', error);
-    }
-  };
-
-  return (
-    <div>
-      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
-      <input
-        value={number}
-        onChange={(e) => setNumber(e.target.value)}
-        placeholder="Enter phone number"
-      />
-      <button onClick={handleCall} disabled={!isConnected}>
-        Call
-      </button>
-      {callStatus === 'ongoing' && (
-        <>
-          <p>Duration: {callDuration}</p>
-          <button onClick={toggleMute}>{isMuted ? 'Unmute' : 'Mute'}</button>
-          <button onClick={hangup}>Hang Up</button>
-        </>
-      )}
-    </div>
-  );
+  // Hang up
+  call.hangup();
+} catch (error) {
+  console.error("Call failed:", error.message);
 }
 ```
 
@@ -133,143 +91,39 @@ function CallInterface() {
 
 ### DoraCell Class
 
-#### Constructor
-
-```typescript
-new DoraCell(config: DoraCellConfig)
-```
+#### `new DoraCell(config)`
 
-**Config options:**
-- `auth` - Authentication configuration (required)
-  - `type: 'api-token'` - Use API token authentication
-  - `apiToken: string` - Your Dora Cell API token
-  - `apiBaseUrl?: string` - API base URL (optional)
-- `turnServers?: RTCIceServer[]` - Custom TURN/STUN servers
-- `debug?: boolean` - Enable debug logging
-- `autoSelectExtension?: boolean` - Auto-select first extension (default: true)
+- `config.auth` (Required)
+  - `type: 'extension' | 'api-token'`
+  - `extension: string` (for extension type)
+  - `apiToken: string` (for api-token type)
+- `config.debug?: boolean` - Enable JsSIP debug logs (default: false)
 
 #### Methods
 
-**`initialize(): Promise<void>`**  
-Initialize the SDK and connect to SIP server.
-
-**`call(phoneNumber: string, options?: CallOptions): Promise<Call>`**  
-Make an outbound call.
-
-Options:
-- `extension?: string` - Specific extension to use for this call
-
-**`hangup(): void`**  
-Hang up the current call.
-
-**`answerCall(): void`**  
-Answer an incoming call.
+- `initialize(): Promise<void>` - Connect to the SIP server.
+- `call(number, options?): Promise<Call>` - Initiate an outbound call.
+- `answerCall(): void` - Answer a pending incoming call.
+- `hangup(): void` - End the current active call.
+- `on(event, handler): void` - Listen for events (e.g., `call:incoming`, `connection:status`).
+- `destroy(): void` - Cleanup and disconnect.
 
-**`getCurrentCall(): Call | null`**  
-Get the current active call.
+## Events
 
-**`getStatus(): ConnectionStatus`**  
-Get current connection status.
-
-**`getExtensions(): string[]`**  
-Get list of available extensions.
-
-**`on(event, handler): void`**  
-Register event listener.
-
-**`off(event, handler): void`**  
-Remove event listener.
-
-**`destroy(): void`**  
-Cleanup and destroy SDK instance.
-
-### Events
-
-```typescript
-sdk.on('connection:status', (state: ConnectionState) => {});
-sdk.on('call:incoming', (call: Call) => {});
-sdk.on('call:outgoing', (call: Call) => {});
-sdk.on('call:ringing', (call: Call) => {});
-sdk.on('call:connected', (call: Call) => {});
-sdk.on('call:ended', (call: Call, reason?: string) => {});
-sdk.on('call:failed', (call: Call, error: string) => {});
-sdk.on('error', (error: Error) => {});
-```
-
-### Call Object
-
-```typescript
-interface Call {
-  id: string;
-  status: CallStatus;
-  direction: 'inbound' | 'outbound';
-  remoteNumber: string;
-  localExtension: string;
-  duration: number;
-  
-  mute(): void;
-  unmute(): void;
-  hangup(): void;
-  isMuted(): boolean;
-}
-```
-
-## Authentication
-
-### Getting an API Token
-
-1. Log in to your Dora Cell dashboard
-2. Navigate to Settings → API Tokens
-3. Generate a new API token
-4. Copy the token and use it in your SDK configuration
-
-### Backend API Endpoint
-
-The SDK expects your backend to provide a `/api/sip-credentials` endpoint that:
-- Accepts `Authorization: Bearer <token>` header
-- Returns SIP credentials in this format:
-
-```json
-{
-  "ws_url": "wss://cell.usedora.com:8089/ws",
-  "sip_uri": "sip:101@64.227.10.164",
-  "password": "your-password",
-  "extensions": [
-    { "extension": "101", "displayName": "Main Line" }
-  ]
-}
-```
-
-## Phone Number Formatting
-
-The SDK automatically handles Nigerian phone number formatting:
-
-- `08012345678` → `sip:2348012345678@domain`
-- `2348012345678` → `sip:2348012345678@domain`
-- `101` (extension) → `sip:101@domain`
-
-## Error Handling
-
-```javascript
-import { AuthenticationError, CallError, ConnectionError } from '@dora-cell/sdk';
-
-try {
-  await sdk.initialize();
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', error.message);
-  } else if (error instanceof ConnectionError) {
-    console.error('Connection failed:', error.message);
-  }
-}
-```
+| Event               | Description                    | Data                                 |
+| ------------------- | ------------------------------ | ------------------------------------ |
+| `connection:status` | SIP registration status change | `{ status: string, error?: string }` |
+| `call:incoming`     | New incoming call detected     | `Call` object                        |
+| `call:outgoing`     | New outbound call started      | `Call` object                        |
+| `call:connected`    | Call answered and connected    | `Call` object                        |
+| `call:ended`        | Call terminated                | `Call` object, `reason: string`      |
+| `error`             | General SDK error              | `Error` object                       |
 
 ## Examples
 
-See the `/examples` directory for complete working examples:
-- `vanilla-js/` - Pure JavaScript implementation
-- `react-app/` - React application
-- `nextjs-app/` - Next.js application
+Check the [`examples/`](../../examples) directory in the main repository:
+
+- `next-js-demo/` - Complete Next.js implementation with React components
 
 ## License
 

package/dist/index.d.mts

@@ -60,6 +60,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -113,6 +114,7 @@ declare class DoraCell {
      * Initialize the SDK - authenticate and connect to SIP server
      */
     initialize(): Promise<void>;
+    private waitForRegistration;
     private initializeUserAgent;
     private setupUserAgentHandlers;
     private initializeCallManager;

package/dist/index.d.ts

@@ -60,6 +60,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -113,6 +114,7 @@ declare class DoraCell {
      * Initialize the SDK - authenticate and connect to SIP server
      */
     initialize(): Promise<void>;
+    private waitForRegistration;
     private initializeUserAgent;
     private setupUserAgentHandlers;
     private initializeCallManager;