sceyt-call 1.1.4 → 1.1.6

package/README.md

@@ -1,24 +1,20 @@
 # Sceyt Call SDK
 
-JavaScript SDK for real-time voice and video calls with WebRTC. Works alongside the [SceytChat SDK](https://www.npmjs.com/package/sceyt-chat).
+JavaScript SDK for real-time voice and video calls with WebRTC. This SDK works alongside the [SceytChat SDK](https://www.npmjs.com/package/sceyt-chat) to provide calling functionality.
 
 ## Table of Contents
 
 * [Installation](#installation)
+* [Prerequisites](#prerequisites)
 * [Quick Start](#quick-start)
-* [Core Flow](#core-flow)
 * [Media Flow Types](#media-flow-types)
-* [Creating a Call](#creating-a-call)
-* [Joining a Call](#joining-a-call)
-* [Answering & Rejecting](#answering--rejecting)
-* [Invite Keys](#invite-keys)
 * [Call Methods](#call-methods)
-* [Call Properties](#call-properties)
+* [Error Handling](#error-handling)
 * [Call Events](#call-events)
 * [Client Events](#client-events)
 * [Call Management](#call-management)
 * [Call History (CDR)](#call-history-cdr)
-* [Error Handling](#error-handling)
+* [Participant States](#participant-states)
 * [Logging](#logging)
 * [TypeScript Support](#typescript-support)
 * [License](#license)
@@ -33,7 +29,7 @@ yarn add sceyt-call
 
 ## Prerequisites
 
-The Sceyt Call SDK requires the [SceytChat SDK](https://www.npmjs.com/package/sceyt-chat) to be installed and connected before initializing the call client.
+The Sceyt Call SDK requires the [SceytChat SDK](https://www.npmjs.com/package/sceyt-chat) to be installed and connected before initializing the call client. The chat client handles authentication and signaling for calls.
 
 ```bash
 npm install sceyt-chat
@@ -46,52 +42,39 @@ const chatClient = new SceytChat('{apiUrl}', '{appId}', '{clientId}');
 await chatClient.connect('{accessToken}');
 ```
 
-For detailed setup, see the [sceyt-chat documentation](https://www.npmjs.com/package/sceyt-chat).
+For detailed chat client setup, see the [sceyt-chat documentation](https://www.npmjs.com/package/sceyt-chat).
 
 ## Quick Start
 
 ```typescript
 import SceytCallClient, { MediaFlow } from 'sceyt-call';
 
+// Initialize call client with connected chat client
 const callClient = new SceytCallClient(chatClient);
 
 // Listen for incoming calls
 callClient.on('invitedToCall', ({ call }) => {
+  console.log(`Incoming call from ${call.createdBy}`);
   call.sendRinging();
-  // call.join(...) when user answers
+  // Show incoming call UI...
 });
 
-// Start a call
-const result = callClient.prepareCall('my-call-id', {
+// Start a call — prepare first, then join
+const result = callClient.prepareCall('call-123', {
   mediaFlow: MediaFlow.P2P,
   participantIds: ['user1', 'user2'],
 });
-if (result.success && result.data) {
-  result.data.join({
-    audioSettings: { publishAudio: true },
-    videoSettings: { publishVideo: true },
-  });
-}
-```
-
-## Core Flow
+const call = result.data;
+call?.join({ audioSettings: { publishAudio: true } });
 
-All calls follow a two-step pattern:
-
-1. **`callClient.prepareCall(callId, createOptions?)`** — Create a local `Call` object (no media yet). The call is placed in `prepareCalls`.
-2. **`call.join(options)`** or **`call.create(errorCallback?)`** — Start signaling and media. On success the call moves to `activeCalls`.
-
-```typescript
-// Prepare with full options
-const result = callClient.prepareCall('call-123', {
-  mediaFlow: MediaFlow.SFU,
-  participantIds: ['user1', 'user2'],
-  videoCall: true,
-  settings: { startsAt: Date.now(), expiresAt: Date.now() + 3600000 },
+// Handle call events
+call.on('callStateChanged', ({ state }) => {
+  console.log(`Call state: ${state}`);
 });
 
-// Prepare with just an invite key (mediaFlow resolved from key)
-const result = callClient.prepareCall(inviteKey);
+call.on('participantStateChanged', ({ participant, state }) => {
+  console.log(`${participant.id} is now ${state}`);
+});
 ```
 
 ## Media Flow Types
@@ -102,189 +85,187 @@ const result = callClient.prepareCall(inviteKey);
 | `MediaFlow.SFU` | Server-routed media (Selective Forwarding Unit) | Group calls |
 | `MediaFlow.S2W` | SIP-to-WebRTC media processing | 1:1 calls |
 
-## Creating a Call
-
-Use `call.create()` to send invitations without joining yourself. All call options (`participantIds`, `metadata`, `settings`, etc.) are set via `prepareCall`.
+## Call Methods
 
 ```typescript
-const result = callClient.prepareCall('my-call-link', {
-  mediaFlow: MediaFlow.SFU,
-  participantIds: ['user1', 'user2'],
-  videoCall: true,
-  metadata: { topic: 'standup' },
-  settings: {
-    expiresAt: Date.now() + 3600000,
-    persistent: true,
-  },
-});
+// Audio controls
+call.mute(true);       // Mute microphone
+call.mute(false);      // Unmute
+call.hold(true);       // Put on hold
 
-result.data?.create((error) => {
-  // Optional: handle server-side error
-  console.error(error.error?.message);
-});
-```
+// Video controls
+await call.enableVideo(true);
+await call.startScreenShare();
+await call.stopScreenShare();
 
-## Joining a Call
+// Device selection
+const cameras = await call.getAvailableVideoDevices();
+await call.selectVideoDevice(cameras[0].deviceId);
 
-```typescript
-// Join only (e.g. incoming call)
-call.join({
-  audioSettings: { publishAudio: true },
-  videoSettings: { publishVideo: false }
-});
+const mics = await call.getAvailableAudioDevices();
+await call.selectAudioDevice(mics[0].deviceId);
 
-// Prepare with participants then join
-const result = callClient.prepareCall('call-123', {
-  mediaFlow: MediaFlow.P2P,
-  participantIds: ['user1'],
-  videoCall: true,
-});
-result.data?.join({
-  audioSettings: { publishAudio: true },
-  videoSettings: { publishVideo: true },
-});
+// Participants
+await call.addParticipants(['user3', 'user4']);
+await call.switchToSFU();  // Upgrade P2P to SFU
 ```
 
-### `JoinCallOptions`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `audioSettings` | `AudioSettings` | Audio publish settings |
-| `videoSettings` | `VideoSettings` | Video publish settings |
-| `useMediaProxy` | `boolean` | Route media through proxy |
-| `localAudioTracks` | `MediaStreamTrack[]` | Custom audio tracks |
-| `localVideoTracks` | `MediaStreamTrack[]` | Custom video tracks |
-
-### `AudioSettings`
+## Error Handling
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `publishAudio` | `boolean` | Publish audio on join. Default: `true` |
-| `preferredAudioRoute` | `string \| null` | Preferred microphone device ID |
+All methods return `CallClientResult<T>` with structured error information instead of throwing exceptions:
 
-### `VideoSettings`
+### Pattern 1: Check Result Success
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `publishVideo` | `boolean` | Publish video on join. Default: `true` |
+```typescript
+const result = await call.enableVideo(true);
+if (!result.success) {
+  console.error('Error:', result.error?.message);
+  console.error('Code:', result.error?.code);
+}
+```
 
-### `CreateCallOptions`
+### Pattern 2: Use Error Callback
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `mediaFlow` | `MediaFlow` | Media routing mode (required) |
-| `participantIds` | `string[]` | User IDs to invite |
-| `videoCall` | `boolean` | Whether this is a video call |
-| `metadata` | `Record<string, string \| number>` | Custom metadata |
-| `settings` | `CallSettings` | Scheduling and broadcast settings |
+Some methods support optional error callbacks for real-time error feedback:
 
-### `CallSettings`
+```typescript
+const handleError = (result) => {
+  if (result.error) {
+    console.error(result.error.message, result.error.code);
+  }
+};
+
+// Synchronous methods — check return value
+const prepareResult = callClient.prepareCall('call-123', { mediaFlow: MediaFlow.P2P });
+if (!prepareResult.success) console.error(prepareResult.error?.message);
+
+// Join — sync result + optional async signal error callback
+const joinResult = call.join({ audioSettings: { publishAudio: true } }, handleError);
+if (!joinResult.success) console.error(joinResult.error?.message);
+
+// Create without joining — optional async signal error callback
+call.create(handleError);
+
+// Ringing notification — optional async signal error callback
+call.sendRinging(handleError);
+
+// Reject — optional async signal error callback
+call.reject('busy', handleError);
+
+// Async methods — await result + optional async signal error callback
+const videoResult = await call.enableVideo(true, handleError);
+await call.startScreenShare(handleError);
+await call.stopScreenShare(handleError);
+call.mute(true, handleError);
+await call.switchToSFU(handleError);
+```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `startsAt` | `number` | Scheduled start time (epoch ms) |
-| `expiresAt` | `number` | Expiry time (epoch ms) |
-| `broadcastSettings` | `BroadcastSettings` | `{ enabled: boolean }` |
-| `persistent` | `boolean` | Keep call alive when all participants leave |
+**Methods Supporting Error Callbacks:**
+- `callClient.prepareCall(callId, options?)` — check return value
+- `call.join(options, errorCallback?)` — signal rejection delivered via callback
+- `call.create(errorCallback?)` — server CREATE rejection delivered via callback
+- `call.sendRinging(errorCallback?)` — signal error delivered via callback
+- `call.reject(reason?, errorCallback?)` — signal error delivered via callback
+- `call.enableVideo(enabled, errorCallback?)` — camera/signal errors via callback
+- `call.startScreenShare(errorCallback?)` — screen share errors via callback
+- `call.stopScreenShare(errorCallback?)` — signal errors via callback
+- `call.mute(mute, errorCallback?)` — signal errors via callback
+- `call.switchToSFU(errorCallback?)` — signal errors via callback
+- `call.leave()` — no callback, check return value
+
+**All Error Codes:**
+
+| Code | Error Type | Cause | Solution |
+|------|-----------|-------|----------|
+| 4000 | `BadSignal` | Invalid signal format | Check signal parameters |
+| 4001 | `CallNotFound` | Call not found in system | Verify call ID exists |
+| 4002 | `ParticipantNotFound` | Participant not in call | Check participant exists |
+| 4003 | `NotAllowed` | Operation not allowed in state | Verify call state |
+| 4004 | `ParticipantAlreadyExists` | Participant already in call | Don't add duplicates |
+| 4005 | `NotAllowed` | Permission denied by user | Enable in browser settings |
+| 4006 | `BadRequest` | Invalid request parameters | Fix parameters |
+| 5001 | `InternalError` | Server-side error | Retry (resendable) |
+| 9901 | `NetworkError` | Network connectivity lost | Check connection (resendable) |
+| 9902 | `Timeout` | Operation timed out | Retry (resendable) |
+| 9903 | `NetworkError` | Network error occurred | Check connection (resendable) |
+| 9904 | `NetworkError` | Network error occurred | Check connection (resendable) |
 
-## Answering & Rejecting
+## Call Events
 
 ```typescript
-callClient.on('invitedToCall', ({ call }) => {
-  call.sendRinging();
-
-  // Answer
-  call.join({ audioSettings: { publishAudio: true } });
+call.on('audioTrackAdded', ({ participant, track }) => {
+  // Play participant's audio
+  const audio = new Audio();
+  audio.srcObject = new MediaStream([track]);
+  audio.play();
+});
 
-  // Reject
-  call.reject('busy');
+call.on('videoTrackAdded', ({ participant, track }) => {
+  // Display participant's video
+  videoElement.srcObject = new MediaStream([track]);
 });
-```
 
-## Invite Keys
+call.on('participantEvent', ({ participant, event }) => {
+  // event: 'Mute' | 'Unmute' | 'Hold' | 'VideoEnabled' | etc.
+});
 
-```typescript
-// Generate a shareable key from an active call
-const key = call.generateInviteKey();
+call.on('activeSpeakersChanged', ({ activeSpeakers }) => {
+  // Handle active speaker detection
+});
 
-// Join via invite key
-const result = callClient.prepareCall(key);
-result.data?.join({ audioSettings: { publishAudio: true } });
+call.on('sessionRenewed', ({ call, sessionId }) => {
+  // Fired when the server assigns a new sessionId to an existing call
+});
 ```
 
-## Call Methods
+## Client Events
 
 ```typescript
-call.mute(true / false);
-call.hold(true / false);
-await call.enableVideo(true / false);
-await call.startScreenShare();
-await call.stopScreenShare();
-call.addParticipants(['user3']);
-await call.switchToSFU();
-await call.selectVideoDevice(deviceId);
-await call.selectAudioDevice(deviceId);
-call.leave();
-call.reject('busy');
-```
-
-## Call Properties
+callClient.on('invitedToCall', ({ call }) => {
+  // Handle incoming call
+});
 
-```typescript
-call.id;               // Unique call identifier
-call.sessionId;        // Server-assigned session ID
-call.mediaFlow;        // Current media flow type
-call.state;            // Current CallState
-call.participants;     // All Participant objects
-call.localParticipant; // The local user's Participant
-call.activeSpeakers;   // ActiveSpeakerInfo[] — currently speaking participants
-call.settings;         // CallSettings (startsAt, expiresAt, persistent, broadcastSettings)
+callClient.on('ongoingCallsUpdated', ({ calls }) => {
+  // Handle call list updates
+});
 ```
 
-## Call Events
+## Call Management
 
 ```typescript
-call.on('callStateChanged', ({ call, state }) => {});
-call.on('participantStateChanged', ({ call, participant, state }) => {});
-call.on('participantConnectionStateChanged', ({ call, participant, state }) => {});
-call.on('participantEvent', ({ call, participant, event }) => {});
-// event: 'Mute' | 'Unmute' | 'Hold' | 'Unhold' | 'VideoEnabled' | 'VideoDisabled'
-//        | 'ScreenSharingStarted' | 'ScreenSharingStopped'
-call.on('participantsAdded', ({ call, participants }) => {});
-call.on('participantsRemoved', ({ call, participants }) => {});
-call.on('audioTrackAdded', ({ call, participant, track }) => {});
-call.on('audioTrackRemoved', ({ call, participant }) => {});
-call.on('videoTrackAdded', ({ call, participant, track }) => {});
-call.on('videoTrackRemoved', ({ call, participant }) => {});
-call.on('activeSpeakersChanged', ({ call, activeSpeakers }) => {});
-call.on('dominantSpeakerChanged', ({ call, dominantSpeaker }) => {});
-call.on('mediaFlowChanged', ({ call, mediaFlow }) => {});
-call.on('sessionRenewed', ({ call, sessionId }) => {
-  // Fired when the server assigns a new sessionId to the call
+// Prepare a call (placed in prepareCalls, no media yet)
+const result = callClient.prepareCall('call-123', {
+  mediaFlow: MediaFlow.SFU,
+  participantIds: ['user1'],
 });
-```
+const call = result.data;
 
-## Client Events
+// Join — moves call from prepareCalls to activeCalls
+call?.join({ audioSettings: { publishAudio: true } });
 
-```typescript
-callClient.on('invitedToCall', ({ call }) => {});
-callClient.on('ongoingCallsUpdated', ({ calls }) => {});
-```
+// Create without joining (sends invites, stays in prepareCalls until server confirms)
+call?.create((error) => console.error(error.error?.message));
 
-## Call Management
+// Accept an incoming call
+callClient.on('invitedToCall', ({ call }) => {
+  call.join({ audioSettings: { publishAudio: true } });
+});
 
-```typescript
-// Calls prepared locally but not yet joined/created
-callClient.prepareCalls;
+// Reject / leave
+call?.reject('busy');
+call?.leave();
 
-// Calls that are actively joined
-callClient.activeCalls;
+// Calls prepared but not yet joined
+const pendingCalls = callClient.prepareCalls;
 
-// Fetch a call by ID (local lookup first, then server)
-const result = await callClient.getCall('call-id');
+// Calls actively joined
+const activeCalls = callClient.activeCalls;
 
-// Refresh and return all server-side ongoing calls
-callClient.getOngoingCalls();
+// Active speakers on a call (updated via 'activeSpeakersChanged' event)
+const speakers = call?.activeSpeakers;
+
+// Fetch a call by ID (local first, then server)
+const { data } = await callClient.getCall('call-id');
 ```
 
 ## Call History (CDR)
@@ -297,59 +278,50 @@ const query = new callClient.RecentCallQueryBuilder()
   .limit(20)
   .build();
 
-const { records } = await query.loadNextPage();
-```
-
-## Error Handling
-
-All methods return `CallClientResult<T>`:
+const { records, hasNext } = await query.loadNextPage();
 
-```typescript
-const result = call.join({ audioSettings: { publishAudio: true } });
-if (!result.success) {
-  console.error(result.error?.message, result.error?.code);
-}
-
-// Optional error callback for async signal errors (create/join)
-result.data?.create((result) => {
-  console.error(result.error?.message);
+records.forEach(record => {
+  console.log(`Call: ${record.callId}`);
+  console.log(`Duration: ${record.endedAt - record.startedAt}ms`);
+  console.log(`Participants: ${record.participants.length}`);
 });
 ```
 
+## Participant States
+
+| State | Description |
+|-------|-------------|
+| `Idle` | Not actively participating |
+| `Ringing` | Device is ringing |
+| `Joined` | In the call |
+| `Left` | Left the call |
+| `Declined` | Declined invitation |
+| `Kicked` | Removed by another user |
+| `NoAnswer` | Did not answer |
+
 ## Logging
 
 ```typescript
-const unsubscribe = callClient.onLog((entry) => {
+callClient.onLog((entry) => {
   console.log(`[${entry.level}] ${entry.prefix}: ${entry.message}`);
 });
-unsubscribe();
 ```
 
 ## TypeScript Support
 
+Full TypeScript support with exported types:
+
 ```typescript
 import type {
-  JoinCallOptions,
-  CreateCallOptions,
-  AudioSettings,
-  VideoSettings,
-  CallSettings,
-  BroadcastSettings,
-  CallClientResult,
+  Call,
+  Participant,
+  IJoinCallOptions,
   CallEventMap,
   CallClientEventMap,
   ICallDetailRecord,
-  ICDRParticipant,
-  Unsubscribe,
-} from 'sceyt-call';
-
-import {
-  MediaFlow,
-  CallState,
   ParticipantState,
-  ParticipantConnectionState,
-  MediaConnectionState,
-  CDRRequestOrder,
+  CallState,
+  MediaFlow
 } from 'sceyt-call';
 ```