@dora-cell/sdk-react 0.1.1-beta.10

package/README.md

@@ -0,0 +1,378 @@
+# @dora-cell/sdk-react
+
+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  
+✅ **Auto state management** - Automatic call state and connection tracking  
+✅ **React 18 & 19 compatible** - Works with latest React versions  
+
+## Installation
+
+```bash
+npm install @dora-cell/sdk @dora-cell/sdk-react jssip
+# or
+yarn add @dora-cell/sdk @dora-cell/sdk-react jssip
+# or
+pnpm add @dora-cell/sdk @dora-cell/sdk-react jssip
+```
+
+## 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.
+
+```tsx
+const config = {
+  auth: {
+    type: 'extension',
+    extension: '1000',
+    // password: '...' // Optional override (default: 1234)
+  }
+};
+```
+
+### 1. Wrap your app with DoraCellProvider
+
+```tsx
+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'
+        },
+        debug: true
+      }}
+    >
+      <YourApp />
+    </DoraCellProvider>
+  );
+}
+```
+
+### 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);
+    }
+  };
+
+  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>
+      )}
+    </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();
+```
+
+**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();
+```
+
+### useDoraCell()
+
+Access the underlying SDK instance directly.
+
+```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.
+
+```tsx
+import { CallInterface } from '@dora-cell/sdk-react';
+
+function MyApp() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <CallInterface 
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        onCallEnded={() => console.log('Call ended')}
+      />
+    </>
+  );
+}
+```
+
+#### Dialpad
+A dialpad component for entering phone numbers and placing calls.
+
+```tsx
+import { Dialpad } from '@dora-cell/sdk-react';
+
+function MyApp() {
+  return (
+    <Dialpad 
+      onCallInitiated={(number) => console.log('Calling:', number)}
+      initialNumber=""
+    />
+  );
+}
+```
+
+## 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;
+}
+```
+
+### Custom Extension Selection
+
+```tsx
+function CallWithExtension() {
+  const sdk = useDoraCell();
+  const [selectedExtension, setSelectedExtension] = useState('');
+
+  const extensions = sdk.getExtensions();
+
+  const makeCall = async (number: string) => {
+    await sdk.call(number, { extension: selectedExtension });
+  };
+
+  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>
+  );
+}
+```
+
+### Error Handling
+
+```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
+    }
+  };
+
+  return (
+    <div>
+      {error && <div className="error">{error.message}</div>}
+      {/* Rest of your UI */}
+    </div>
+  );
+}
+```
+
+## TypeScript Support
+
+All hooks and components are fully typed. Import types as needed:
+
+```typescript
+import type { Call, CallStatus, ConnectionStatus } from '@dora-cell/sdk';
+import type { DoraCellConfig } from '@dora-cell/sdk-react';
+```
+
+## Examples
+
+See the `/examples` directory in the main repository for complete working examples:
+- `react-app/` - React application with hooks
+- `nextjs-app/` - Next.js application
+
+## Requirements
+
+- React 18.0.0 or higher (including React 19)
+- @dora-cell/sdk (peer dependency)
+- jssip (peer dependency)
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@dora-cell/sdk](https://www.npmjs.com/package/@dora-cell/sdk) - Core VoIP SDK

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+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;
+        value: string;
+    }>;
+    selectedExtension?: string;
+    onExtensionChange?: (ext: string) => void;
+}
+declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions, selectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
+
+interface DoraCellContextValue {
+    sdk: DoraCell | null;
+    connectionStatus: ConnectionStatus;
+    currentCall: Call | null;
+    callStatus: CallStatus;
+    callDuration: string;
+    isMuted: boolean;
+    isInitialized: boolean;
+    error: Error | null;
+    call: (phoneNumber: string, extension?: string) => Promise<void>;
+    hangup: () => void;
+    toggleMute: () => void;
+    answerCall: () => void;
+}
+interface DoraCellProviderProps {
+    config: DoraCellConfig;
+    children: React.ReactNode;
+    autoInitialize?: boolean;
+}
+declare function DoraCellProvider({ config, children, autoInitialize, }: DoraCellProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Dora Cell SDK context
+ */
+declare function useDoraCell(): DoraCellContextValue;
+/**
+ * Hook for making calls
+ */
+declare function useCall(): {
+    call: (phoneNumber: string, extension?: string) => Promise<void>;
+    hangup: () => void;
+    toggleMute: () => void;
+    answerCall: () => void;
+    callStatus: CallStatus;
+    callDuration: string;
+    isMuted: boolean;
+    currentCall: Call | null;
+};
+/**
+ * Hook for connection status
+ */
+declare function useConnectionStatus(): {
+    connectionStatus: ConnectionStatus;
+    isInitialized: boolean;
+    isConnected: boolean;
+    error: Error | null;
+};
+
+export { CallInterface, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+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;
+        value: string;
+    }>;
+    selectedExtension?: string;
+    onExtensionChange?: (ext: string) => void;
+}
+declare function Dialpad({ onCallInitiated, initialNumber, showKeys, className, availableExtensions, selectedExtension, onExtensionChange, }: DialpadProps): react_jsx_runtime.JSX.Element;
+
+interface DoraCellContextValue {
+    sdk: DoraCell | null;
+    connectionStatus: ConnectionStatus;
+    currentCall: Call | null;
+    callStatus: CallStatus;
+    callDuration: string;
+    isMuted: boolean;
+    isInitialized: boolean;
+    error: Error | null;
+    call: (phoneNumber: string, extension?: string) => Promise<void>;
+    hangup: () => void;
+    toggleMute: () => void;
+    answerCall: () => void;
+}
+interface DoraCellProviderProps {
+    config: DoraCellConfig;
+    children: React.ReactNode;
+    autoInitialize?: boolean;
+}
+declare function DoraCellProvider({ config, children, autoInitialize, }: DoraCellProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Dora Cell SDK context
+ */
+declare function useDoraCell(): DoraCellContextValue;
+/**
+ * Hook for making calls
+ */
+declare function useCall(): {
+    call: (phoneNumber: string, extension?: string) => Promise<void>;
+    hangup: () => void;
+    toggleMute: () => void;
+    answerCall: () => void;
+    callStatus: CallStatus;
+    callDuration: string;
+    isMuted: boolean;
+    currentCall: Call | null;
+};
+/**
+ * Hook for connection status
+ */
+declare function useConnectionStatus(): {
+    connectionStatus: ConnectionStatus;
+    isInitialized: boolean;
+    isConnected: boolean;
+    error: Error | null;
+};
+
+export { CallInterface, Dialpad, DoraCellProvider, type DoraCellProviderProps, useCall, useConnectionStatus, useDoraCell };