@dora-cell/sdk 0.1.1-beta.6

package/README.md

@@ -0,0 +1,276 @@
+# @dora-cell/sdk
+
+VoIP calling SDK for Dora Cell - Make calls from any JavaScript application without logging into the Dora Cell web app.
+
+## Features
+
+✅ **Framework-agnostic** - Works with vanilla JS, React, Vue, Angular, etc.  
+✅ **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  
+
+## Installation
+
+```bash
+npm install @dora-cell/sdk jssip
+# or
+yarn add @dora-cell/sdk jssip
+# or
+pnpm add @dora-cell/sdk jssip
+```
+
+For React projects:
+```bash
+npm install @dora-cell/sdk @dora-cell/sdk-react jssip
+```
+
+## Quick Start
+
+### Vanilla JavaScript
+
+```javascript
+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'
+  },
+  debug: true // Enable console logging
+});
+
+// Initialize connection
+await sdk.initialize();
+
+// Listen for connection status
+sdk.on('connection:status', (state) => {
+  console.log('Connection status:', state.status);
+});
+
+// Listen for call events
+sdk.on('call:connected', (call) => {
+  console.log('Call connected:', call.remoteNumber);
+});
+
+sdk.on('call:ended', (call, reason) => {
+  console.log('Call ended:', reason);
+});
+
+// Make a call
+const call = await sdk.call('+2348012345678');
+
+// Mute/unmute
+call.mute();
+call.unmute();
+
+// Hang up
+call.hangup();
+```
+
+### 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>
+  );
+}
+
+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>
+  );
+}
+```
+
+## API Reference
+
+### DoraCell Class
+
+#### Constructor
+
+```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)
+
+#### 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) => {});
+```
+
+### 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);
+  }
+}
+```
+
+## Examples
+
+See the `/examples` directory for complete working examples:
+- `vanilla-js/` - Pure JavaScript implementation
+- `react-app/` - React application
+- `nextjs-app/` - Next.js application
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,210 @@
+import EventEmitter from 'eventemitter3';
+
+/**
+ * Core TypeScript type definitions for Dora Cell SDK
+ */
+interface ApiTokenAuth {
+    type: 'api-token';
+    apiToken: string;
+    apiBaseUrl?: string;
+}
+interface DirectCredentialsAuth {
+    type: 'direct';
+    sipUri: string;
+    password: string;
+    wsUrl: string;
+}
+type AuthConfig = ApiTokenAuth | DirectCredentialsAuth;
+interface DoraCellConfig {
+    auth: AuthConfig;
+    sipServer?: string;
+    turnServers?: RTCIceServer[];
+    debug?: boolean;
+    autoSelectExtension?: boolean;
+}
+interface SipCredentials {
+    wsUrl: string;
+    sipUri: string;
+    password: string;
+    sipDomain?: string;
+    extensions?: Extension[];
+    expiresIn?: number;
+}
+interface Extension {
+    extension: string;
+    displayName?: string;
+    isPrimary?: boolean;
+}
+type CallStatus = 'idle' | 'connecting' | 'ringing' | 'ongoing' | 'ended';
+type CallDirection = 'inbound' | 'outbound';
+interface CallOptions {
+    extension?: string;
+    mediaConstraints?: MediaStreamConstraints;
+}
+interface Call {
+    id: string;
+    status: CallStatus;
+    direction: CallDirection;
+    remoteNumber: string;
+    localExtension: string;
+    duration: number;
+    startTime?: number;
+    endTime?: number;
+    mute(): void;
+    unmute(): void;
+    hangup(): void;
+    isMuted(): boolean;
+}
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
+interface ConnectionState {
+    status: ConnectionStatus;
+    extension?: string;
+    error?: string;
+}
+type DoraCellEventMap = {
+    'connection:status': (state: ConnectionState) => void;
+    'call:incoming': (call: Call) => void;
+    'call:outgoing': (call: Call) => void;
+    'call:ringing': (call: Call) => void;
+    'call:connected': (call: Call) => void;
+    'call:ended': (call: Call, reason?: string) => void;
+    'call:failed': (call: Call, error: string) => void;
+    'error': (error: Error) => void;
+};
+type DoraCellEvent = keyof DoraCellEventMap;
+declare class DoraCellError extends Error {
+    code?: string | undefined;
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, details?: any | undefined);
+}
+declare class AuthenticationError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+declare class CallError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+declare class ConnectionError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+
+/**
+ * Dora Cell SDK - Main entry point
+ * Framework-agnostic VoIP calling SDK using JsSIP
+ */
+
+declare class DoraCell {
+    private config;
+    private events;
+    private authProvider;
+    private credentials;
+    private ua;
+    private callManager;
+    private connectionStatus;
+    private retryCount;
+    private maxRetries;
+    constructor(config: DoraCellConfig);
+    /**
+     * Initialize the SDK - authenticate and connect to SIP server
+     */
+    initialize(): Promise<void>;
+    private initializeUserAgent;
+    private setupUserAgentHandlers;
+    private initializeCallManager;
+    /**
+     * Make an outbound call
+     */
+    call(phoneNumber: string, options?: CallOptions): Promise<Call>;
+    /**
+     * Answer an incoming call
+     */
+    answerCall(): void;
+    /**
+     * Hangup the current call
+     */
+    hangup(): void;
+    /**
+     * Get current call
+     */
+    getCurrentCall(): Call | null;
+    /**
+     * Get connection status
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get available extensions
+     */
+    getExtensions(): string[];
+    /**
+     * Event listener management
+     */
+    on<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    off<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    once<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    /**
+     * Cleanup and destroy the SDK instance
+     */
+    destroy(): void;
+    private emitConnectionStatus;
+    private emitError;
+    private getDefaultTurnServers;
+    private getDisplayName;
+    private generateInstanceId;
+}
+
+/**
+ * Call Manager - Handles individual call sessions
+ * Extracted and refactored from JsSIPProvider.tsx
+ */
+
+declare class CallSession implements Call {
+    id: string;
+    status: CallStatus;
+    direction: CallDirection;
+    remoteNumber: string;
+    localExtension: string;
+    duration: number;
+    startTime?: number;
+    endTime?: number;
+    private session;
+    private _isMuted;
+    private remoteStreamValue;
+    private durationInterval?;
+    private events;
+    constructor(session: any, direction: CallDirection, remoteNumber: string, localExtension: string, events: EventEmitter);
+    private generateCallId;
+    private setupSessionHandlers;
+    private handleCallEnd;
+    private startDurationTimer;
+    private stopDurationTimer;
+    mute(): void;
+    unmute(): void;
+    hangup(): void;
+    isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
+    getFormattedDuration(): string;
+    destroy(): void;
+}
+
+/**
+ * Phone number formatting utilities
+ * Extracted from JsSIPProvider.tsx
+ */
+/**
+ * Format a phone number to SIP URI format
+ * Handles Nigerian numbers, international format, and local extensions
+ */
+declare function formatPhoneToSIP(phone: string, sipDomain: string): string;
+/**
+ * Normalize a phone number to E.164 format
+ */
+declare function normalizePhoneNumber(phone: string, countryCode?: string): string;
+/**
+ * Extract extension/number from SIP URI
+ */
+declare function extractNumberFromSipUri(sipUri: string): string;
+/**
+ * Validate phone number format
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import EventEmitter from 'eventemitter3';
+
+/**
+ * Core TypeScript type definitions for Dora Cell SDK
+ */
+interface ApiTokenAuth {
+    type: 'api-token';
+    apiToken: string;
+    apiBaseUrl?: string;
+}
+interface DirectCredentialsAuth {
+    type: 'direct';
+    sipUri: string;
+    password: string;
+    wsUrl: string;
+}
+type AuthConfig = ApiTokenAuth | DirectCredentialsAuth;
+interface DoraCellConfig {
+    auth: AuthConfig;
+    sipServer?: string;
+    turnServers?: RTCIceServer[];
+    debug?: boolean;
+    autoSelectExtension?: boolean;
+}
+interface SipCredentials {
+    wsUrl: string;
+    sipUri: string;
+    password: string;
+    sipDomain?: string;
+    extensions?: Extension[];
+    expiresIn?: number;
+}
+interface Extension {
+    extension: string;
+    displayName?: string;
+    isPrimary?: boolean;
+}
+type CallStatus = 'idle' | 'connecting' | 'ringing' | 'ongoing' | 'ended';
+type CallDirection = 'inbound' | 'outbound';
+interface CallOptions {
+    extension?: string;
+    mediaConstraints?: MediaStreamConstraints;
+}
+interface Call {
+    id: string;
+    status: CallStatus;
+    direction: CallDirection;
+    remoteNumber: string;
+    localExtension: string;
+    duration: number;
+    startTime?: number;
+    endTime?: number;
+    mute(): void;
+    unmute(): void;
+    hangup(): void;
+    isMuted(): boolean;
+}
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed';
+interface ConnectionState {
+    status: ConnectionStatus;
+    extension?: string;
+    error?: string;
+}
+type DoraCellEventMap = {
+    'connection:status': (state: ConnectionState) => void;
+    'call:incoming': (call: Call) => void;
+    'call:outgoing': (call: Call) => void;
+    'call:ringing': (call: Call) => void;
+    'call:connected': (call: Call) => void;
+    'call:ended': (call: Call, reason?: string) => void;
+    'call:failed': (call: Call, error: string) => void;
+    'error': (error: Error) => void;
+};
+type DoraCellEvent = keyof DoraCellEventMap;
+declare class DoraCellError extends Error {
+    code?: string | undefined;
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, details?: any | undefined);
+}
+declare class AuthenticationError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+declare class CallError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+declare class ConnectionError extends DoraCellError {
+    constructor(message: string, details?: any);
+}
+
+/**
+ * Dora Cell SDK - Main entry point
+ * Framework-agnostic VoIP calling SDK using JsSIP
+ */
+
+declare class DoraCell {
+    private config;
+    private events;
+    private authProvider;
+    private credentials;
+    private ua;
+    private callManager;
+    private connectionStatus;
+    private retryCount;
+    private maxRetries;
+    constructor(config: DoraCellConfig);
+    /**
+     * Initialize the SDK - authenticate and connect to SIP server
+     */
+    initialize(): Promise<void>;
+    private initializeUserAgent;
+    private setupUserAgentHandlers;
+    private initializeCallManager;
+    /**
+     * Make an outbound call
+     */
+    call(phoneNumber: string, options?: CallOptions): Promise<Call>;
+    /**
+     * Answer an incoming call
+     */
+    answerCall(): void;
+    /**
+     * Hangup the current call
+     */
+    hangup(): void;
+    /**
+     * Get current call
+     */
+    getCurrentCall(): Call | null;
+    /**
+     * Get connection status
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get available extensions
+     */
+    getExtensions(): string[];
+    /**
+     * Event listener management
+     */
+    on<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    off<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    once<K extends DoraCellEvent>(event: K, handler: DoraCellEventMap[K]): void;
+    /**
+     * Cleanup and destroy the SDK instance
+     */
+    destroy(): void;
+    private emitConnectionStatus;
+    private emitError;
+    private getDefaultTurnServers;
+    private getDisplayName;
+    private generateInstanceId;
+}
+
+/**
+ * Call Manager - Handles individual call sessions
+ * Extracted and refactored from JsSIPProvider.tsx
+ */
+
+declare class CallSession implements Call {
+    id: string;
+    status: CallStatus;
+    direction: CallDirection;
+    remoteNumber: string;
+    localExtension: string;
+    duration: number;
+    startTime?: number;
+    endTime?: number;
+    private session;
+    private _isMuted;
+    private remoteStreamValue;
+    private durationInterval?;
+    private events;
+    constructor(session: any, direction: CallDirection, remoteNumber: string, localExtension: string, events: EventEmitter);
+    private generateCallId;
+    private setupSessionHandlers;
+    private handleCallEnd;
+    private startDurationTimer;
+    private stopDurationTimer;
+    mute(): void;
+    unmute(): void;
+    hangup(): void;
+    isMuted(): boolean;
+    getRemoteStream(): MediaStream | null;
+    getFormattedDuration(): string;
+    destroy(): void;
+}
+
+/**
+ * Phone number formatting utilities
+ * Extracted from JsSIPProvider.tsx
+ */
+/**
+ * Format a phone number to SIP URI format
+ * Handles Nigerian numbers, international format, and local extensions
+ */
+declare function formatPhoneToSIP(phone: string, sipDomain: string): string;
+/**
+ * Normalize a phone number to E.164 format
+ */
+declare function normalizePhoneNumber(phone: string, countryCode?: string): string;
+/**
+ * Extract extension/number from SIP URI
+ */
+declare function extractNumberFromSipUri(sipUri: string): string;
+/**
+ * Validate phone number format
+ */
+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 };