@dora-cell/sdk 0.1.1-beta.9 → 1.0.1

package/README.md

@@ -8,124 +8,101 @@ 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  
-✅ **Auto-extension selection** - Automatically selects first available extension  
-✅ **React bindings** - Optional React hooks for easy integration  
+✅ **API Token Auth** - Securely authenticate with Public & Secret keys  
+✅ **Dynamic Extensions** - Fetch and switch between DID numbers  
+✅ **Wallet Integration** - Check credit balance directly from the SDK  
+✅ **React bindings** - Premium UI components and hooks included
 
 ## 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);
-});
+Best for production apps. The SDK will verify keys and fetch SIP credentials automatically.
 
-// Listen for call events
-sdk.on('call:connected', (call) => {
-  console.log('Call connected:', call.remoteNumber);
+```javascript
+const sdk = new DoraCell({
+  auth: {
+    type: "api-token",
+    publicKey: "pk_live_...",
+    secretKey: "sk_live_...",
+  },
 });
+```
+
+#### 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 +110,64 @@ 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: 'api-token' | 'extension' | 'direct'`
+  - `publicKey/secretKey` (for api-token)
+  - `extension` (for extension type)
+- `config.environment?: 'dev' | 'staging' | 'production'` - Shortcut for API URLs (default: 'production')
+- `config.autoSelectExtension?: boolean` - Register first available DID (default: true)
+- `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>` - Authenticate and register with the SIP server.
+- `call(number, extension?): Promise<Call>` - Initiate an outbound call.
+- `getWallet(): Promise<{ balance: number, currency: string }>` - Get current credit balance.
+- `fetchExtensions(): Promise<Extension[]>` - Fetch available DID numbers/extensions.
+- `setExtension(ext): Promise<void>` - Switch active extension and re-register SIP.
+- `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, extension?: 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

@@ -5,8 +5,8 @@ import EventEmitter from 'eventemitter3';
  */
 interface ApiTokenAuth {
     type: 'api-token';
-    apiToken: string;
-    apiBaseUrl?: string;
+    publicKey: string;
+    secretKey: string;
 }
 interface DirectCredentialsAuth {
     type: 'direct';
@@ -21,8 +21,11 @@ interface ExtensionAuth {
     sipDomain?: string;
 }
 type AuthConfig = ApiTokenAuth | DirectCredentialsAuth | ExtensionAuth;
+type DoraCellEnv = 'dev' | 'staging' | 'production' | 'local';
 interface DoraCellConfig {
     auth: AuthConfig;
+    apiBaseUrl?: string;
+    environment?: DoraCellEnv;
     sipServer?: string;
     turnServers?: RTCIceServer[];
     debug?: boolean;
@@ -60,6 +63,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -105,6 +109,8 @@ declare class DoraCell {
     private credentials;
     private ua;
     private callManager;
+    private apiClient;
+    private apiBaseUrl;
     private connectionStatus;
     private retryCount;
     private maxRetries;
@@ -113,6 +119,7 @@ declare class DoraCell {
      * Initialize the SDK - authenticate and connect to SIP server
      */
     initialize(): Promise<void>;
+    private waitForRegistration;
     private initializeUserAgent;
     private setupUserAgentHandlers;
     private initializeCallManager;
@@ -132,14 +139,29 @@ declare class DoraCell {
      * Get current call
      */
     getCurrentCall(): Call | null;
+    /**
+     * Get user's wallet/credit balance
+     */
+    getWallet(): Promise<{
+        balance: number;
+        currency: string;
+    }>;
     /**
      * Get connection status
      */
     getStatus(): ConnectionStatus;
     /**
-     * Get available extensions
+     * Fetch available extensions (DID numbers) from the API
+     */
+    fetchExtensions(): Promise<any[]>;
+    /**
+     * Get available extensions (DID numbers)
+     */
+    getExtensions(): any[];
+    /**
+     * Update active extension and re-initialize SIP connection
      */
-    getExtensions(): string[];
+    setExtension(extension: string): Promise<void>;
     /**
      * Event listener management
      */
@@ -155,6 +177,7 @@ declare class DoraCell {
     private getDefaultTurnServers;
     private getDisplayName;
     private generateInstanceId;
+    private resolveApiBaseUrl;
 }
 
 /**
@@ -213,4 +236,4 @@ declare function extractNumberFromSipUri(sipUri: string): string;
  */
 declare function isValidPhoneNumber(phone: string, minLength?: number): boolean;
 
-export { type ApiTokenAuth, type AuthConfig, AuthenticationError, type Call, type CallDirection, CallError, type CallOptions, CallSession, type CallStatus, ConnectionError, type ConnectionState, type ConnectionStatus, type DirectCredentialsAuth, DoraCell, type DoraCellConfig, DoraCellError, type DoraCellEvent, type DoraCellEventMap, type Extension, type SipCredentials, DoraCell as default, extractNumberFromSipUri, formatPhoneToSIP, isValidPhoneNumber, normalizePhoneNumber };
+export { type ApiTokenAuth, type AuthConfig, AuthenticationError, type Call, type CallDirection, CallError, type CallOptions, CallSession, type CallStatus, ConnectionError, type ConnectionState, type ConnectionStatus, type DirectCredentialsAuth, DoraCell, type DoraCellConfig, DoraCellError, type DoraCellEvent, type DoraCellEventMap, type Extension, type ExtensionAuth, type SipCredentials, DoraCell as default, extractNumberFromSipUri, formatPhoneToSIP, isValidPhoneNumber, normalizePhoneNumber };

package/dist/index.d.ts

@@ -5,8 +5,8 @@ import EventEmitter from 'eventemitter3';
  */
 interface ApiTokenAuth {
     type: 'api-token';
-    apiToken: string;
-    apiBaseUrl?: string;
+    publicKey: string;
+    secretKey: string;
 }
 interface DirectCredentialsAuth {
     type: 'direct';
@@ -21,8 +21,11 @@ interface ExtensionAuth {
     sipDomain?: string;
 }
 type AuthConfig = ApiTokenAuth | DirectCredentialsAuth | ExtensionAuth;
+type DoraCellEnv = 'dev' | 'staging' | 'production' | 'local';
 interface DoraCellConfig {
     auth: AuthConfig;
+    apiBaseUrl?: string;
+    environment?: DoraCellEnv;
     sipServer?: string;
     turnServers?: RTCIceServer[];
     debug?: boolean;
@@ -60,6 +63,7 @@ interface Call {
     unmute(): void;
     hangup(): void;
     isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
 }
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
 interface ConnectionState {
@@ -105,6 +109,8 @@ declare class DoraCell {
     private credentials;
     private ua;
     private callManager;
+    private apiClient;
+    private apiBaseUrl;
     private connectionStatus;
     private retryCount;
     private maxRetries;
@@ -113,6 +119,7 @@ declare class DoraCell {
      * Initialize the SDK - authenticate and connect to SIP server
      */
     initialize(): Promise<void>;
+    private waitForRegistration;
     private initializeUserAgent;
     private setupUserAgentHandlers;
     private initializeCallManager;
@@ -132,14 +139,29 @@ declare class DoraCell {
      * Get current call
      */
     getCurrentCall(): Call | null;
+    /**
+     * Get user's wallet/credit balance
+     */
+    getWallet(): Promise<{
+        balance: number;
+        currency: string;
+    }>;
     /**
      * Get connection status
      */
     getStatus(): ConnectionStatus;
     /**
-     * Get available extensions
+     * Fetch available extensions (DID numbers) from the API
+     */
+    fetchExtensions(): Promise<any[]>;
+    /**
+     * Get available extensions (DID numbers)
+     */
+    getExtensions(): any[];
+    /**
+     * Update active extension and re-initialize SIP connection
      */
-    getExtensions(): string[];
+    setExtension(extension: string): Promise<void>;
     /**
      * Event listener management
      */
@@ -155,6 +177,7 @@ declare class DoraCell {
     private getDefaultTurnServers;
     private getDisplayName;
     private generateInstanceId;
+    private resolveApiBaseUrl;
 }
 
 /**
@@ -213,4 +236,4 @@ declare function extractNumberFromSipUri(sipUri: string): string;
  */
 declare function isValidPhoneNumber(phone: string, minLength?: number): boolean;
 
-export { type ApiTokenAuth, type AuthConfig, AuthenticationError, type Call, type CallDirection, CallError, type CallOptions, CallSession, type CallStatus, ConnectionError, type ConnectionState, type ConnectionStatus, type DirectCredentialsAuth, DoraCell, type DoraCellConfig, DoraCellError, type DoraCellEvent, type DoraCellEventMap, type Extension, type SipCredentials, DoraCell as default, extractNumberFromSipUri, formatPhoneToSIP, isValidPhoneNumber, normalizePhoneNumber };
+export { type ApiTokenAuth, type AuthConfig, AuthenticationError, type Call, type CallDirection, CallError, type CallOptions, CallSession, type CallStatus, ConnectionError, type ConnectionState, type ConnectionStatus, type DirectCredentialsAuth, DoraCell, type DoraCellConfig, DoraCellError, type DoraCellEvent, type DoraCellEventMap, type Extension, type ExtensionAuth, type SipCredentials, DoraCell as default, extractNumberFromSipUri, formatPhoneToSIP, isValidPhoneNumber, normalizePhoneNumber };