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

package/README.md

@@ -5,374 +5,169 @@ React hooks and components for the Dora Cell VoIP SDK.
 ## Features
 
 ✅ **React Hooks** - Easy-to-use hooks for call management  
-✅ **Context Provider** - Simple setup with DoraCellProvider  
-✅ **TypeScript support** - Full type definitions included  
+✅ **Context Provider** - Simple setup with `DoraCellProvider`  
+✅ **Pre-built UI** - Includes `Dialpad`, `CallInterface`, and `CreditBalance`  
 ✅ **Auto state management** - Automatic call state and connection tracking  
-✅ **React 18 & 19 compatible** - Works with latest React versions  
+✅ **DID Management** - Hooks to fetch and switch between caller IDs
 
 ## Installation
 
 ```bash
-npm install @dora-cell/sdk @dora-cell/sdk-react jssip
+npm install @dora-cell/sdk @dora-cell/sdk-react
 # or
-yarn add @dora-cell/sdk @dora-cell/sdk-react jssip
+yarn add @dora-cell/sdk @dora-cell/sdk-react
 # or
-pnpm add @dora-cell/sdk @dora-cell/sdk-react jssip
+pnpm add @dora-cell/sdk @dora-cell/sdk-react
 ```
 
-## Quick Start
-
-### Authentication
-
-You can authenticate using either an API Token (recommended for production) or Direct SIP Credentials (useful for testing/development).
-
-#### Option 1: API Token (Production)
-The SDK will fetch SIP credentials from your backend using the token.
-```tsx
-const config = {
-  auth: {
-    type: 'api-token',
-    apiToken: 'YOUR_API_TOKEN',
-    // apiBaseUrl: 'https://api.your-backend.com' (Optional)
-  }
-};
-```
-
-#### Option 2: Extension Authentication (Plug & Play)
-You can connect using just your extension number. The SDK handles the server configuration automatically.
+> [!NOTE]
+> `@dora-cell/sdk` is a peer dependency of this package. `jssip` will be installed automatically as a dependency of the SDK.
 
-```tsx
-const config = {
-  auth: {
-    type: 'extension',
-    extension: '1000',
-    // password: '...' // Optional override (default: 1234)
-  }
-};
-```
+## Quick Start
 
 ### 1. Wrap your app with DoraCellProvider
 
 ```tsx
-import { DoraCellProvider } from '@dora-cell/sdk-react';
+import { DoraCellProvider } from "@dora-cell/sdk-react";
 
 function App() {
   return (
     <DoraCellProvider
       config={{
         auth: {
-          type: 'api-token',
-          apiToken: 'your-api-token-here',
-          apiBaseUrl: 'https://api.usedora.com'
+          type: "api-token",
+          publicKey: "pk_...",
+          secretKey: "sk_...",
         },
-        debug: true
+        environment: "production",
       }}
+      autoInitialize={true}
     >
-      <YourApp />
+      <MainApp />
     </DoraCellProvider>
   );
 }
 ```
 
-### 2. Use hooks in your components
+### 2. Use Hooks in your components
 
 ```tsx
-import { useCall, useConnectionStatus } from '@dora-cell/sdk-react';
-
-function CallInterface() {
-  const { 
-    call, 
-    hangup, 
-    toggleMute, 
-    callStatus, 
-    callDuration, 
-    isMuted,
-    currentCall 
-  } = useCall();
-  
-  const { isConnected, status } = useConnectionStatus();
-  const [number, setNumber] = useState('');
-
-  const handleCall = async () => {
-    try {
-      await call(number);
-    } catch (error) {
-      console.error('Call failed:', error);
-    }
-  };
+import { useCall, useConnectionStatus } from "@dora-cell/sdk-react";
+
+function CallManager() {
+  const { call, callStatus, callDuration } = useCall();
+  const { isConnected } = useConnectionStatus();
 
   return (
     <div>
-      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
-      
-      {callStatus === 'idle' && (
-        <>
-          <input
-            value={number}
-            onChange={(e) => setNumber(e.target.value)}
-            placeholder="Enter phone number"
-          />
-          <button onClick={handleCall} disabled={!isConnected}>
-            Call
-          </button>
-        </>
-      )}
-      
-      {callStatus === 'ongoing' && (
-        <>
-          <p>Call with: {currentCall?.remoteNumber}</p>
-          <p>Duration: {callDuration}</p>
-          <button onClick={toggleMute}>
-            {isMuted ? 'Unmute' : 'Mute'}
-          </button>
-          <button onClick={hangup}>Hang Up</button>
-        </>
-      )}
-      
-      {callStatus === 'ringing' && (
-        <p>Ringing...</p>
-      )}
+      <p>Status: {isConnected ? "Ready" : "Connecting..."}</p>
+      {callStatus === "ongoing" && <p>Talking: {callDuration}</p>}
+      <button onClick={() => call("08012345678")} disabled={!isConnected}>
+        Call Now
+      </button>
     </div>
   );
 }
 ```
 
-## API Reference
-
-### DoraCellProvider
-
-Wrap your app with this provider to enable SDK functionality.
-
-```tsx
-<DoraCellProvider
-  config={{
-    auth: {
-      type: 'api-token',
-      apiToken: string,
-      apiBaseUrl?: string
-    },
-    turnServers?: RTCIceServer[],
-    debug?: boolean,
-    autoSelectExtension?: boolean
-  }}
->
-  {children}
-</DoraCellProvider>
-```
-
-### useCall()
-
-Hook for managing calls.
-
-```typescript
-const {
-  // Methods
-  call: (phoneNumber: string) => Promise<void>,
-  hangup: () => void,
-  answerCall: () => void,
-  toggleMute: () => void,
-  
-  // State
-  callStatus: 'idle' | 'ringing' | 'ongoing',
-  callDuration: string, // Formatted as "MM:SS"
-  isMuted: boolean,
-  currentCall: Call | null,
-  error: Error | null
-} = useCall();
-```
+## UI Components
 
-**Methods:**
-- `call(phoneNumber)` - Make an outbound call
-- `hangup()` - End the current call
-- `answerCall()` - Answer an incoming call
-- `toggleMute()` - Toggle mute/unmute
-
-**State:**
-- `callStatus` - Current call status
-- `callDuration` - Formatted call duration (e.g., "01:23")
-- `isMuted` - Whether the call is muted
-- `currentCall` - Current call object with details
-- `error` - Any call-related errors
-
-### useConnectionStatus()
-
-Hook for monitoring connection status.
-
-```typescript
-const {
-  isConnected: boolean,
-  status: 'disconnected' | 'connecting' | 'connected' | 'error',
-  error: Error | null
-} = useConnectionStatus();
-```
+We provide high-level components that match the Dora Cell design language.
 
-### useDoraCell()
+### `CallInterface`
 
-Access the underlying SDK instance directly.
+A slide-over interface that handles the entire call lifecycle (Ringing, Connecting, Ongoing, Mute controls). 
 
-```typescript
-const sdk = useDoraCell();
-
-// Use SDK methods directly
-sdk.getExtensions();
-sdk.on('call:incoming', (call) => {
-  console.log('Incoming call from:', call.remoteNumber);
-});
-```
-
-### UI Components
-
-The SDK includes pre-built UI components for typical call flows.
-
-#### CallInterface
-A complete active call modal that handles ringing, connecting, and ongoing call states.
+> [!TIP]
+> This component handles audio playback (remote stream and ringtones) automatically. You just need to ensure it's rendered in your tree when a call is active.
 
 ```tsx
-import { CallInterface } from '@dora-cell/sdk-react';
+import { CallInterface } from "@dora-cell/sdk-react";
 
-function MyApp() {
+function Dashboard() {
   const [isOpen, setIsOpen] = useState(false);
 
   return (
     <>
-      <CallInterface 
-        isOpen={isOpen}
-        onOpenChange={setIsOpen}
-        onCallEnded={() => console.log('Call ended')}
-      />
+      {/* 
+        This should be rendered globally (e.g., in your root layout) 
+        to handle incoming calls even when the dialer is closed.
+      */}
+      <CallInterface isOpen={isOpen} onOpenChange={setIsOpen} />
     </>
   );
 }
 ```
 
-#### Dialpad
-A dialpad component for entering phone numbers and placing calls.
+### `Dialpad`
+
+A flexible keypad for entering numbers and initiating calls. It automatically fetches available Caller IDs (extensions) and allows switching between them.
+
+### `CreditBalance`
+
+A standalone component that displays the user's current credit balance and currency. It automatically refreshes whenever the SDK initializes and whenever a call ends.
 
 ```tsx
-import { Dialpad } from '@dora-cell/sdk-react';
+import { CreditBalance } from "@dora-cell/sdk-react";
 
-function MyApp() {
+function Header() {
   return (
-    <Dialpad 
-      onCallInitiated={(number) => console.log('Calling:', number)}
-      initialNumber=""
-    />
+    <header>
+      <h1>My App</h1>
+      <CreditBalance />
+    </header>
   );
 }
 ```
 
-## Advanced Usage
-
-### Handling Incoming Calls
-
-```tsx
-function IncomingCallHandler() {
-  const { currentCall, answerCall, hangup, callStatus } = useCall();
-  const sdk = useDoraCell();
-
-  useEffect(() => {
-    const handleIncoming = (call) => {
-      // Show notification or UI for incoming call
-      console.log('Incoming call from:', call.remoteNumber);
-    };
-
-    sdk.on('call:incoming', handleIncoming);
-    return () => sdk.off('call:incoming', handleIncoming);
-  }, [sdk]);
-
-  if (callStatus === 'ringing' && currentCall?.direction === 'inbound') {
-    return (
-      <div>
-        <p>Incoming call from {currentCall.remoteNumber}</p>
-        <button onClick={answerCall}>Answer</button>
-        <button onClick={hangup}>Decline</button>
-      </div>
-    );
-  }
-
-  return null;
-}
-```
+## API Reference
 
-### Custom Extension Selection
+### `useCall()`
 
-```tsx
-function CallWithExtension() {
-  const sdk = useDoraCell();
-  const [selectedExtension, setSelectedExtension] = useState('');
+Returns methods and state for the active call.
 
-  const extensions = sdk.getExtensions();
+- `call(number)`: Initiate a call.
+- `hangup()`: End current call.
+- `answerCall()`: Answer incoming call.
+- `toggleMute()`: Toggle microphone.
+- `callStatus`: `'idle' | 'connecting' | 'ringing' | 'ongoing' | 'ended'`.
+- `callDuration`: Formatted string `"00:00"`.
+- `isMuted`: Boolean state.
 
-  const makeCall = async (number: string) => {
-    await sdk.call(number, { extension: selectedExtension });
-  };
+### `useConnectionStatus()`
 
-  return (
-    <div>
-      <select 
-        value={selectedExtension} 
-        onChange={(e) => setSelectedExtension(e.target.value)}
-      >
-        {extensions.map(ext => (
-          <option key={ext} value={ext}>{ext}</option>
-        ))}
-      </select>
-      {/* Rest of your call UI */}
-    </div>
-  );
-}
-```
+Returns the SIP registration state.
 
-### Error Handling
+- `isConnected`: `true` when registered and ready.
+- `connectionStatus`: `'disconnected' | 'connecting' | 'connected' | 'registered' | 'registrationFailed'`.
+- `extension`: The currently registered extension number.
+- `error`: Any connection error object.
 
-```tsx
-function CallWithErrorHandling() {
-  const { call, error, callStatus } = useCall();
-  const [number, setNumber] = useState('');
-
-  const handleCall = async () => {
-    try {
-      await call(number);
-    } catch (err) {
-      console.error('Call failed:', err);
-      // Show error to user
-    }
-  };
+### `useWallet()`
 
-  return (
-    <div>
-      {error && <div className="error">{error.message}</div>}
-      {/* Rest of your UI */}
-    </div>
-  );
-}
-```
+Returns the user's credit balance.
 
-## TypeScript Support
+- `balance`: Numerical balance.
+- `currency`: Currency code (e.g., `"NGN"`).
+- `isLoading`: Boolean loading state.
+- `refresh()`: Fetch the latest balance.
 
-All hooks and components are fully typed. Import types as needed:
+### `useExtensions()`
 
-```typescript
-import type { Call, CallStatus, ConnectionStatus } from '@dora-cell/sdk';
-import type { DoraCellConfig } from '@dora-cell/sdk-react';
-```
+Returns available Caller IDs.
 
-## Examples
+- `extensions`: Array of available DID numbers/extensions.
+- `setExtension(ext)`: Switch to a different Caller ID.
+- `isLoading`: Boolean loading state.
 
-See the `/examples` directory in the main repository for complete working examples:
-- `react-app/` - React application with hooks
-- `nextjs-app/` - Next.js application
+## Styling
 
-## Requirements
+The components use Tailwind CSS internally. To avoid conflicts, all styles are prefixed with `dora-`. You must import the CSS file in your main entry file (e.g., `layout.tsx` or `App.tsx`):
 
-- React 18.0.0 or higher (including React 19)
-- @dora-cell/sdk (peer dependency)
-- jssip (peer dependency)
+```javascript
+import "@dora-cell/sdk-react/styles.css";
+```
 
 ## License
 
 MIT
-
-## Related Packages
-
-- [@dora-cell/sdk](https://www.npmjs.com/package/@dora-cell/sdk) - Core VoIP SDK

package/dist/index.d.mts

@@ -3,45 +3,18 @@ import React from 'react';
 import { DoraCellConfig, CallStatus, Call, ConnectionStatus, DoraCell } from '@dora-cell/sdk';
 
 interface CallInterfaceProps {
-    /**
-     * Whether the interface is open/visible
-     */
     isOpen?: boolean;
-    /**
-     * Callback when visibility changes
-     */
     onOpenChange?: (open: boolean) => void;
-    /**
-     * Callback when call ends (useful for invalidating queries)
-     */
     onCallEnded?: () => void;
-    /**
-     * Custom maximize icon component
-     */
     maximizeIcon?: React.ReactNode;
-    /**
-     * Custom minimize icon component
-     */
     minimizeIcon?: React.ReactNode;
 }
 declare function CallInterface({ isOpen, onOpenChange, onCallEnded, maximizeIcon, minimizeIcon, }: CallInterfaceProps): react_jsx_runtime.JSX.Element | null;
 
 interface DialpadProps {
-    /**
-     * Callback when call is initiated
-     */
     onCallInitiated?: (number: string) => void;
-    /**
-     * Initial number to populate
-     */
     initialNumber?: string;
-    /**
-     * Whether to show the dialpad keys (0-9)
-     */
     showKeys?: boolean;
-    /**
-     * Custom class name for the container
-     */
     className?: string;
     availableExtensions?: Array<{
         label: string;
@@ -50,7 +23,7 @@ interface DialpadProps {
     selectedExtension?: string;
     onExtensionChange?: (ext: string) => void;
 }
-declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions, selectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
+declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions: providedExtensions, selectedExtension: providedSelectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
 
 interface DoraCellContextValue {
     sdk: DoraCell | null;
@@ -61,6 +34,7 @@ interface DoraCellContextValue {
     isMuted: boolean;
     isInitialized: boolean;
     error: Error | null;
+    extension: string | null;
     call: (phoneNumber: string, extension?: string) => Promise<void>;
     hangup: () => void;
     toggleMute: () => void;
@@ -88,6 +62,7 @@ declare function useCall(): {
     callDuration: string;
     isMuted: boolean;
     currentCall: Call | null;
+    callError: string | undefined;
 };
 /**
  * Hook for connection status
@@ -97,6 +72,31 @@ declare function useConnectionStatus(): {
     isInitialized: boolean;
     isConnected: boolean;
     error: Error | null;
+    extension: string | null;
 };
+/**
+ * Hook to fetch wallet/credit balance
+ */
+declare function useWallet(): {
+    balance: number;
+    currency: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Hook for managing extensions (DID numbers)
+ */
+declare function useExtensions(): {
+    extensions: any[];
+    isLoading: boolean;
+    error: Error | null;
+    setExtension: (extension: string) => Promise<void>;
+    refresh: () => Promise<void>;
+};
+/**
+ * Credit Balance component - mirrors main app style
+ */
+declare function CreditBalance(): react_jsx_runtime.JSX.Element;
 
-export { CallInterface, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell };
+export { CallInterface, CreditBalance, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell, useExtensions, useWallet };

package/dist/index.d.ts

@@ -3,45 +3,18 @@ import React from 'react';
 import { DoraCellConfig, CallStatus, Call, ConnectionStatus, DoraCell } from '@dora-cell/sdk';
 
 interface CallInterfaceProps {
-    /**
-     * Whether the interface is open/visible
-     */
     isOpen?: boolean;
-    /**
-     * Callback when visibility changes
-     */
     onOpenChange?: (open: boolean) => void;
-    /**
-     * Callback when call ends (useful for invalidating queries)
-     */
     onCallEnded?: () => void;
-    /**
-     * Custom maximize icon component
-     */
     maximizeIcon?: React.ReactNode;
-    /**
-     * Custom minimize icon component
-     */
     minimizeIcon?: React.ReactNode;
 }
 declare function CallInterface({ isOpen, onOpenChange, onCallEnded, maximizeIcon, minimizeIcon, }: CallInterfaceProps): react_jsx_runtime.JSX.Element | null;
 
 interface DialpadProps {
-    /**
-     * Callback when call is initiated
-     */
     onCallInitiated?: (number: string) => void;
-    /**
-     * Initial number to populate
-     */
     initialNumber?: string;
-    /**
-     * Whether to show the dialpad keys (0-9)
-     */
     showKeys?: boolean;
-    /**
-     * Custom class name for the container
-     */
     className?: string;
     availableExtensions?: Array<{
         label: string;
@@ -50,7 +23,7 @@ interface DialpadProps {
     selectedExtension?: string;
     onExtensionChange?: (ext: string) => void;
 }
-declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions, selectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
+declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions: providedExtensions, selectedExtension: providedSelectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
 
 interface DoraCellContextValue {
     sdk: DoraCell | null;
@@ -61,6 +34,7 @@ interface DoraCellContextValue {
     isMuted: boolean;
     isInitialized: boolean;
     error: Error | null;
+    extension: string | null;
     call: (phoneNumber: string, extension?: string) => Promise<void>;
     hangup: () => void;
     toggleMute: () => void;
@@ -88,6 +62,7 @@ declare function useCall(): {
     callDuration: string;
     isMuted: boolean;
     currentCall: Call | null;
+    callError: string | undefined;
 };
 /**
  * Hook for connection status
@@ -97,6 +72,31 @@ declare function useConnectionStatus(): {
     isInitialized: boolean;
     isConnected: boolean;
     error: Error | null;
+    extension: string | null;
 };
+/**
+ * Hook to fetch wallet/credit balance
+ */
+declare function useWallet(): {
+    balance: number;
+    currency: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Hook for managing extensions (DID numbers)
+ */
+declare function useExtensions(): {
+    extensions: any[];
+    isLoading: boolean;
+    error: Error | null;
+    setExtension: (extension: string) => Promise<void>;
+    refresh: () => Promise<void>;
+};
+/**
+ * Credit Balance component - mirrors main app style
+ */
+declare function CreditBalance(): react_jsx_runtime.JSX.Element;
 
-export { CallInterface, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell };
+export { CallInterface, CreditBalance, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell, useExtensions, useWallet };