@dora-cell/sdk 0.1.1-beta.6 → 1.0.0

package/README.md

@@ -8,124 +8,100 @@ 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
 
 ```bash
-npm install @dora-cell/sdk jssip
+npm install @dora-cell/sdk
 # or
-yarn add @dora-cell/sdk jssip
+yarn add @dora-cell/sdk
 # or
-pnpm add @dora-cell/sdk jssip
+pnpm add @dora-cell/sdk
 ```
 
-For React projects:
-```bash
-npm install @dora-cell/sdk @dora-cell/sdk-react jssip
-```
+> [!NOTE]
+> `jssip` is a dependency of this SDK and will be installed automatically. You only need to install it manually if you want to use a specific version.
 
 ## 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", // Optional override
+  },
 });
+```
+
+#### Option C: Direct Credentials (Advanced)
 
-sdk.on('call:ended', (call, reason) => {
-  console.log('Call ended:', reason);
+If you already have SIP credentials.
+
+```javascript
+const sdk = new DoraCell({
+  auth: {
+    type: "direct",
+    sipUri: "sip:1001@voice.example.com",
+    password: "your-password",
+    wsUrl: "wss://voice.example.com:8089/ws",
+  },
 });
+```
 
-// Make a call
-const call = await sdk.call('+2348012345678');
+### 2. Connect and Register
 
-// Mute/unmute
-call.mute();
-call.unmute();
+```javascript
+// Listen for registration
+sdk.on("connection:status", (state) => {
+  if (state.status === "registered") {
+    console.log("SIP Ready to make calls!");
+  }
+});
 
-// Hang up
-call.hangup();
+// Initialize connection
+await sdk.initialize();
 ```
 
-### 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>
-  );
-}
+### 3. Make a Call
+
+```javascript
+try {
+  const call = await sdk.call("+2348012345678");
+
+  // 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 +109,61 @@ function CallInterface() {
 
 ### DoraCell Class
 
-#### Constructor
+#### `new DoraCell(config)`
 
-```typescript
-new DoraCell(config: DoraCellConfig)
-```
-
-**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.
-
-**`getCurrentCall(): Call | null`**  
-Get the current active call.
-
-**`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) => {});
-```
+- `initialize(): Promise<void>` - Connect to the SIP server and register the extension.
+- `call(number, options?): Promise<Call>` - Initiate an outbound call.
+  - `options.extension`: Specify a specific extension to call from.
+  - `options.mediaConstraints`: Custom WebRTC media constraints.
+- `answerCall(): void` - Answer a pending incoming call.
+- `hangup(): void` - End the current active call.
+- `on(event, handler): void` - Listen for events (see below).
+- `destroy(): void` - Cleanup and disconnect.
 
 ### 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
+Returned by `call()` and emitted in events.
 
-The SDK automatically handles Nigerian phone number formatting:
+- `id`: Unique call ID.
+- `status`: `'idle' | 'connecting' | 'ringing' | 'ongoing' | 'ended'`.
+- `direction`: `'inbound' | 'outbound'`.
+- `remoteNumber`: The other party's number.
+- `duration`: Call duration in seconds.
+- `mute()` / `unmute()`: Control microphone.
+- `hangup()`: End this specific call.
+- `getRemoteStream()`: Returns the WebRTC `MediaStream` for audio playback.
 
-- `08012345678` → `sip:2348012345678@domain`
-- `2348012345678` → `sip:2348012345678@domain`
-- `101` (extension) → `sip:101@domain`
+## Events
 
-## Error Handling
+| 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:ringing`      | Remote party is ringing        | `Call` object                      |
+| `call:connected`    | Call answered and connected    | `Call` object                      |
+| `call:ended`        | Call terminated                | `Call` object, `reason: string`    |
+| `call:failed`       | Call failed to connect         | `Call` object, `error: string`     |
+| `error`             | General SDK error              | `Error` object                     |
 
-```javascript
-import { AuthenticationError, CallError, ConnectionError } from '@dora-cell/sdk';
+## Browser Requirements
 
-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);
-  }
-}
-```
+- **HTTPS**: WebRTC and microphone access require a secure context (HTTPS or localhost).
+- **Environment**: Modern browsers with WebRTC support (Chrome, Firefox, Safari, Edge).
 
 ## 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

@@ -14,7 +14,13 @@ interface DirectCredentialsAuth {
     password: string;
     wsUrl: string;
 }
-type AuthConfig = ApiTokenAuth | DirectCredentialsAuth;
+interface ExtensionAuth {
+    type: 'extension';
+    extension: string;
+    password?: string;
+    sipDomain?: string;
+}
+type AuthConfig = ApiTokenAuth | DirectCredentialsAuth | ExtensionAuth;
 interface DoraCellConfig {
     auth: AuthConfig;
     sipServer?: string;
@@ -54,6 +60,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -107,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

@@ -14,7 +14,13 @@ interface DirectCredentialsAuth {
     password: string;
     wsUrl: string;
 }
-type AuthConfig = ApiTokenAuth | DirectCredentialsAuth;
+interface ExtensionAuth {
+    type: 'extension';
+    extension: string;
+    password?: string;
+    sipDomain?: string;
+}
+type AuthConfig = ApiTokenAuth | DirectCredentialsAuth | ExtensionAuth;
 interface DoraCellConfig {
     auth: AuthConfig;
     sipServer?: string;
@@ -54,6 +60,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -107,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;