@sawport/peers-caller 0.0.0

package/README.md

@@ -0,0 +1,782 @@
+# 🎥 PeersCaller
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/@sawport%2Fpeers-caller.svg)](https://badge.fury.io/js/@sawport%2Fpeers-caller)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern, TypeScript-first WebRTC library for multi-peer mesh video calls supporting up to 4 participants. Built with developer experience in mind.
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🎥 **WebRTC-based P2P video calls** - Direct peer-to-peer communication
+- �️ **Mesh architecture** - Efficient network topology for up to 4 participants
+- � **TypeScript-first** - Full type safety and excellent IntelliSense
+- ⚡ **Vite-powered** - Lightning-fast development and builds
+- 🎯 **Zustand state management** - Predictable and reactive state
+- 🎛️ **Media controls** - Audio/video toggle, screen sharing
+- 📹 **Call recording** - Built-in recording capabilities
+- 🧪 **Well-tested** - Comprehensive test suite with Vitest
+- 🎨 **React hooks** - Ready-to-use React integration
+- 📡 **Real-time signaling** - WebSocket-based call coordination
+
+## 📦 Installation
+
+```bash
+npm install @sawport/peers-caller
+# or
+yarn add @sawport/peers-caller
+# or
+pnpm add @sawport/peers-caller
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { PeersCaller } from '@sawport/peers-caller';
+
+// Initialize the caller
+const peersCaller = new PeersCaller({
+  conversationId: 'unique-conversation-id',
+  userId: 'current-user-id',
+  token: 'jwt-auth-token',
+  socketUrl: 'https://your-signaling-server.com',
+  maxParticipants: 4,
+  mediaConfig: {
+    video: true,
+    audio: true
+  }
+}, {
+  onParticipantJoined: (participant) => console.log('User joined:', participant.userId),
+  onParticipantLeft: (userId) => console.log('User left:', userId),
+  onStreamReceived: (userId, stream) => {
+    // Attach stream to video element
+    const videoElement = document.getElementById(`video-${userId}`);
+    if (videoElement) videoElement.srcObject = stream;
+  },
+  onError: (error, message) => console.error('Call error:', error, message)
+});
+
+// Start or join a call
+async function startCall() {
+  try {
+    await peersCaller.initialize();
+    await peersCaller.startCall();
+    console.log('Call started successfully!');
+  } catch (error) {
+    console.error('Failed to start call:', error);
+  }
+}
+
+async function joinCall() {
+  try {
+    await peersCaller.initialize();
+    await peersCaller.joinCall();
+    console.log('Joined call successfully!');
+  } catch (error) {
+    console.error('Failed to join call:', error);
+  }
+}
+```
+
+### React Integration
+
+```tsx
+import { useVideoCall } from '@sawport/peers-caller';
+
+function VideoCallComponent() {
+  const {
+    startCall,
+    joinCall,
+    endCall,
+    toggleAudio,
+    toggleVideo,
+    startScreenShare,
+    stopScreenShare,
+    participants,
+    localParticipant,
+    isConnected,
+    error
+  } = useVideoCall({
+    conversationId: 'conversation-123',
+    userId: 'user-456',
+    token: 'your-jwt-token',
+    socketUrl: 'https://your-server.com',
+    callbacks: {
+      onStreamReceived: (userId, stream) => {
+        // Handle received video streams
+        console.log(`Received stream from ${userId}`);
+      }
+    }
+  });
+
+  return (
+    <div className="video-call">
+      <div className="controls">
+        <button onClick={() => startCall()}>Start Call</button>
+        <button onClick={() => joinCall()}>Join Call</button>
+        <button onClick={() => endCall()}>End Call</button>
+        <button onClick={() => toggleAudio(!localParticipant?.audioOn)}>
+          {localParticipant?.audioOn ? 'Mute' : 'Unmute'}
+        </button>
+        <button onClick={() => toggleVideo(!localParticipant?.videoOn)}>
+          {localParticipant?.videoOn ? 'Stop Video' : 'Start Video'}
+        </button>
+        <button onClick={() => startScreenShare()}>Share Screen</button>
+      </div>
+
+      <div className="participants">
+        {Object.values(participants).map(participant => (
+          <div key={participant.userId} className="participant">
+            <video 
+              autoPlay 
+              playsInline 
+              ref={ref => {
+                if (ref && participant.stream) {
+                  ref.srcObject = participant.stream;
+                }
+              }}
+            />
+            <span>{participant.userId}</span>
+          </div>
+        ))}
+      </div>
+
+      {error && <div className="error">Error: {error}</div>}
+    </div>
+  );
+}
+```
+
+## 🏗️ Backend Signaling Requirements
+
+PeersCaller requires a WebSocket signaling server to coordinate calls between peers. The server must implement the following Socket.IO events:
+
+### 📡 Client-to-Server Events (Outgoing)
+
+```typescript
+// Call Management
+socket.emit('call.start', { conversationId: string });
+socket.emit('call.join', { conversationId: string });
+socket.emit('call.leave', { conversationId: string });
+socket.emit('call.end', { conversationId: string, targetUserId?: string });
+socket.emit('call.status', { conversationId: string });
+
+// WebRTC Signaling
+socket.emit('call.offer', { 
+  to: string, 
+  offer: RTCSessionDescriptionInit, 
+  conversationId: string 
+});
+socket.emit('call.answer', { 
+  to: string, 
+  answer: RTCSessionDescriptionInit, 
+  conversationId: string 
+});
+socket.emit('call.candidate', { 
+  to: string, 
+  candidate: RTCIceCandidateInit, 
+  conversationId: string 
+});
+
+// State Updates
+socket.emit('call.state', { 
+  to?: string, 
+  state: Partial<CallParticipant>, 
+  conversationId: string 
+});
+
+// Recording & Transcription
+socket.emit('call.recording.start', { conversationId: string, recordingId: string });
+socket.emit('call.recording.chunk', { conversationId: string, recordingId: string, chunk: Blob });
+socket.emit('call.recording.end', { conversationId: string, recordingId: string });
+socket.emit('call.transcript', { conversationId: string, transcript: string, timestamp: number });
+```
+
+### 📨 Server-to-Client Events (Incoming)
+
+```typescript
+// Call Management Responses
+socket.on('call.started', (data: { 
+  conversationId: string, 
+  userId: string, 
+  success: boolean, 
+  participants: string[] 
+}) => {});
+
+socket.on('call.participant.joined', (data: { 
+  userId: string, 
+  participants: string[], 
+  conversationId: string 
+}) => {});
+
+socket.on('call.participant.left', (data: { 
+  userId: string, 
+  participants: string[], 
+  conversationId: string 
+}) => {});
+
+socket.on('call.participants', (data: { 
+  participants: string[], 
+  conversationId: string 
+}) => {});
+
+socket.on('call.left', (data: { 
+  conversationId: string, 
+  success: boolean 
+}) => {});
+
+socket.on('call.ended', (data: { 
+  conversationId: string, 
+  endedBy: string, 
+  reason: string 
+}) => {});
+
+socket.on('call.error', (data: { 
+  error: string, 
+  message: string 
+}) => {});
+
+// WebRTC Signaling Forwarding
+socket.on('call.offer', (data: { 
+  from: string, 
+  offer: RTCSessionDescriptionInit, 
+  conversationId: string 
+}) => {});
+
+socket.on('call.answer', (data: { 
+  from: string, 
+  answer: RTCSessionDescriptionInit, 
+  conversationId: string 
+}) => {});
+
+socket.on('call.candidate', (data: { 
+  from: string, 
+  candidate: RTCIceCandidateInit, 
+  conversationId: string 
+}) => {});
+
+socket.on('call.state', (data: { 
+  from: string, 
+  state: Partial<CallParticipant>, 
+  conversationId: string 
+}) => {});
+
+// Call Status Updates
+socket.on('call.status.changed', (data: {
+  conversationId: string,
+  hasActiveCall: boolean,
+  participantCount: number,
+  maxParticipants: number,
+  participants: string[],
+  startedAt: Date | null,
+  canJoin: boolean,
+  status: "no_call" | "active" | "full" | "ending"
+}) => {});
+
+// Recording Events
+socket.on('call.recording.start', (data: { recordingId: string, conversationId: string }) => {});
+socket.on('call.recording.chunk.received', (data: { recordingId: string, conversationId: string, chunkSize: number, timestamp: number }) => {});
+socket.on('call.recording.end', (data: { recordingId: string, conversationId: string }) => {});
+
+// Transcription Events
+socket.on('call.transcript', (data: { userId: string, transcript: string, timestamp: number, conversationId: string }) => {});
+```
+
+### 🔐 Authentication
+
+The signaling server should authenticate connections using the provided JWT token:
+
+```typescript
+// Client connection with auth
+io(serverUrl, {
+  path: '/apis/video-call',
+  auth: {
+    token: 'your-jwt-token'
+  }
+});
+```
+
+### 📋 Server Implementation Requirements
+
+1. **Room Management**: Track participants in conversation rooms
+2. **Message Forwarding**: Route WebRTC signaling between specific participants
+3. **Participant Limits**: Enforce maximum participant limits (default: 4)
+4. **Authentication**: Validate JWT tokens and extract user information
+5. **Error Handling**: Provide meaningful error messages and codes
+6. **Graceful Cleanup**: Handle disconnections and cleanup resources
+
+### 🔗 Example Server Setup (Node.js + Socket.IO)
+
+```typescript
+import { Server } from 'socket.io';
+import jwt from 'jsonwebtoken';
+
+const io = new Server(server, {
+  path: '/apis/video-call',
+  cors: { origin: "*" }
+});
+
+// Authentication middleware
+io.use((socket, next) => {
+  const token = socket.handshake.auth.token;
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    socket.userId = decoded.userId;
+    next();
+  } catch (err) {
+    next(new Error('Authentication failed'));
+  }
+});
+
+io.on('connection', (socket) => {
+  console.log(`User ${socket.userId} connected`);
+
+  // Handle call start
+  socket.on('call.start', async ({ conversationId }) => {
+    try {
+      // Join room
+      await socket.join(conversationId);
+      
+      // Get existing participants
+      const room = io.sockets.adapter.rooms.get(conversationId);
+      const participants = Array.from(room || []);
+      
+      // Emit success response
+      socket.emit('call.started', {
+        conversationId,
+        userId: socket.userId,
+        success: true,
+        participants: participants.map(id => io.sockets.sockets.get(id)?.userId).filter(Boolean)
+      });
+      
+      // Notify other participants
+      socket.to(conversationId).emit('call.participant.joined', {
+        userId: socket.userId,
+        participants: participants.map(id => io.sockets.sockets.get(id)?.userId).filter(Boolean),
+        conversationId
+      });
+    } catch (error) {
+      socket.emit('call.error', { error: 'CALL_START_FAILED', message: error.message });
+    }
+  });
+
+  // Handle WebRTC signaling
+  socket.on('call.offer', ({ to, offer, conversationId }) => {
+    const targetSocket = Array.from(io.sockets.sockets.values())
+      .find(s => s.userId === to);
+    
+    if (targetSocket) {
+      targetSocket.emit('call.offer', {
+        from: socket.userId,
+        offer,
+        conversationId
+      });
+    }
+  });
+
+  // Handle disconnection
+  socket.on('disconnect', () => {
+    // Notify rooms about participant leaving
+    socket.rooms.forEach(room => {
+      if (room !== socket.id) {
+        socket.to(room).emit('call.participant.left', {
+          userId: socket.userId,
+          conversationId: room
+        });
+      }
+    });
+  });
+});
+```
+
+## 📚 API Reference
+
+### PeersCaller Class
+
+The main orchestrator class for managing video calls.
+
+#### Constructor
+
+```typescript
+new PeersCaller(config: PeersCallerConfig, callbacks?: PeersCallerCallbacks)
+```
+
+**Parameters:**
+- `config`: Configuration object for the caller
+- `callbacks`: Optional event callbacks
+
+#### Methods
+
+##### `initialize(): Promise<void>`
+Initialize the PeersCaller and establish WebSocket connection.
+
+##### `startCall(mediaConfig?: MediaStreamConfig): Promise<void>`
+Start a new video call.
+
+##### `joinCall(mediaConfig?: MediaStreamConfig): Promise<void>`
+Join an existing video call.
+
+##### `endCall(): Promise<void>`
+End the call for all participants.
+
+##### `leaveCall(): Promise<void>`
+Leave the call gracefully.
+
+##### `toggleAudio(enabled: boolean): void`
+Enable or disable local audio.
+
+##### `toggleVideo(enabled: boolean): void`
+Enable or disable local video.
+
+##### `startScreenShare(): Promise<void>`
+Start sharing screen.
+
+##### `stopScreenShare(): Promise<void>`
+Stop sharing screen.
+
+##### `startRecording(recordingData: RecordingData, config?: RecordingConfig): Promise<void>`
+Start recording the call.
+
+##### `stopRecording(): Promise<void>`
+Stop recording the call.
+
+##### `checkCallStatus(): Promise<CallStatusResponse>`
+Check the current status of the call.
+
+##### `cleanup(): void`
+Clean up all resources and disconnect.
+
+### Configuration Types
+
+#### `PeersCallerConfig`
+
+```typescript
+interface PeersCallerConfig {
+  conversationId: string;        // Unique conversation identifier
+  userId: string;                // Current user's unique identifier
+  token: string;                 // JWT authentication token
+  socketUrl: string;             // WebSocket server URL
+  socketPath?: string;           // Socket.IO path (default: '/apis/video-call')
+  iceServers?: RTCIceServer[];   // STUN/TURN servers
+  mediaConfig?: MediaStreamConfig; // Default media configuration
+  maxParticipants?: number;      // Maximum participants (default: 4)
+  debug?: boolean;               // Enable debug logging
+}
+```
+
+#### `MediaStreamConfig`
+
+```typescript
+interface MediaStreamConfig {
+  video: boolean | MediaTrackConstraints;
+  audio: boolean | MediaTrackConstraints;
+}
+```
+
+#### `PeersCallerCallbacks`
+
+```typescript
+interface PeersCallerCallbacks {
+  onCallStarted?: (data: { conversationId: string; success: boolean; participants: string[] }) => void;
+  onCallEnded?: (data: { conversationId: string; endedBy: string; reason: string }) => void;
+  onParticipantJoined?: (participant: CallParticipant) => void;
+  onParticipantLeft?: (userId: string) => void;
+  onParticipantStateChanged?: (userId: string, state: Partial<CallParticipant>) => void;
+  onStreamReceived?: (userId: string, stream: MediaStream) => void;
+  onCallStateChanged?: (state: "idle" | "connecting" | "connected" | "disconnecting" | "failed") => void;
+  onCallStatusChanged?: (statusInfo: CallStatusResponse) => void;
+  onRecordingStateChanged?: (isRecording: boolean) => void;
+  onError?: (error: PeersCallerError, message: string) => void;
+}
+```
+
+### React Hooks
+
+#### `useVideoCall(options: UseVideoCallOptions)`
+
+A comprehensive React hook for video call functionality.
+
+```typescript
+const {
+  // Core methods
+  initialize,
+  startCall,
+  joinCall,
+  endCall,
+  
+  // Media controls
+  toggleAudio,
+  toggleVideo,
+  startScreenShare,
+  stopScreenShare,
+  
+  // Recording
+  startRecording,
+  stopRecording,
+  
+  // State
+  callState,
+  participants,
+  localParticipant,
+  isConnected,
+  isRecording,
+  error,
+  
+  // Utility
+  cleanup,
+  peersCaller
+} = useVideoCall(options);
+```
+
+### Error Types
+
+```typescript
+type PeersCallerError =
+  | "MEDIA_ACCESS_DENIED"
+  | "PEER_CONNECTION_FAILED"
+  | "SIGNALING_ERROR"
+  | "RECORDING_FAILED"
+  | "TRANSCRIPTION_FAILED"
+  | "CALL_LIMIT_EXCEEDED"
+  | "INVALID_CONVERSATION_ID"
+  | "NETWORK_ERROR"
+  | "UNKNOWN_ERROR";
+```
+
+## 🔧 Advanced Usage
+
+### Custom Media Constraints
+
+```typescript
+const peersCaller = new PeersCaller({
+  // ... other config
+  mediaConfig: {
+    video: {
+      width: { ideal: 1280 },
+      height: { ideal: 720 },
+      frameRate: { ideal: 30 }
+    },
+    audio: {
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true
+    }
+  }
+});
+```
+
+### Custom ICE Servers
+
+```typescript
+const peersCaller = new PeersCaller({
+  // ... other config
+  iceServers: [
+    { urls: 'stun:stun.l.google.com:19302' },
+    { 
+      urls: 'turn:your-turn-server.com:3478',
+      username: 'username',
+      credential: 'password'
+    }
+  ]
+});
+```
+
+### Recording with Custom Configuration
+
+```typescript
+await peersCaller.startRecording(
+  {
+    id: 'recording-123',
+    filename: 'meeting-recording.webm',
+    conversationId: 'conversation-456',
+    startTime: Date.now()
+  },
+  {
+    mimeType: 'video/webm;codecs=vp9',
+    videoBitsPerSecond: 2500000,
+    audioBitsPerSecond: 128000,
+    interval: 1000 // 1 second chunks
+  }
+);
+```
+
+### State Management Integration
+
+```typescript
+import { useCallStore } from '@sawport/peers-caller';
+
+function CallStatus() {
+  const { 
+    isCalling, 
+    callStatus, 
+    participants, 
+    error 
+  } = useCallStore();
+
+  return (
+    <div>
+      <p>Status: {callStatus}</p>
+      <p>Participants: {Object.keys(participants).length}</p>
+      {error && <p>Error: {error}</p>}
+    </div>
+  );
+}
+```
+
+## 🧪 Development
+
+### Prerequisites
+
+- Node.js 18+ (recommended: 20+)
+- Yarn (using Yarn Berry/v3+)
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/sawport/peers-caller.git
+cd peers-caller
+
+# Install dependencies
+yarn install
+
+# Start development server with hot reload
+yarn dev
+
+# Build the library
+yarn build
+
+# Build TypeScript declarations only
+yarn build:types
+```
+
+### Development Scripts
+
+```bash
+# Development
+yarn dev          # Start Vite dev server with hot reload
+yarn build        # Build production bundle
+yarn preview      # Preview production build
+
+# Testing
+yarn test         # Run tests once
+yarn test:watch   # Run tests in watch mode
+yarn test:ui      # Open Vitest UI
+yarn test:coverage # Generate coverage report
+
+# Type checking
+yarn type-check   # Check TypeScript types without building
+```
+
+### Testing
+
+This project uses **Vitest** for testing with comprehensive coverage reporting and WebRTC API mocking.
+
+This project uses Vitest for testing with comprehensive coverage reporting.
+
+#### Running Tests
+
+```bash
+# Run tests once
+yarn test
+
+# Run tests in watch mode (for development)
+yarn test:watch
+
+# Run tests with coverage report
+yarn test:coverage
+
+# Open Vitest UI
+yarn test:ui
+```
+
+#### Test Structure
+
+- `__tests__/` - Integration and setup tests
+- `src/**/*.test.ts` - Unit tests alongside source code
+- `src/test-utils.ts` - Shared test utilities and mocks
+
+#### Writing Tests
+
+The test environment includes:
+
+- **WebRTC API mocks** - RTCPeerConnection, MediaDevices, etc.
+- **External library mocks** - simple-peer, socket.io-client
+- **jsdom environment** - For DOM testing
+- **TypeScript support** - Full type checking in tests
+
+Example test:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { generatePeerId } from '../utils';
+
+describe('generatePeerId', () => {
+  it('should generate unique peer IDs', () => {
+    const id1 = generatePeerId();
+    const id2 = generatePeerId();
+    
+    expect(id1).not.toBe(id2);
+    expect(id1).toMatch(/^peer_\d+_[a-z0-9]{1,9}$/);
+  });
+});
+```
+
+#### Coverage Thresholds
+
+The project maintains high test coverage standards:
+
+- **Branches**: 80%
+- **Functions**: 80%
+- **Lines**: 80%
+- **Statements**: 80%
+
+### CI/CD
+
+GitHub Actions automatically:
+
+- ✅ Runs tests on Node.js 18.x, 20.x, 22.x
+- ✅ Checks TypeScript compilation
+- ✅ Generates coverage reports
+- ✅ Builds the library
+- ✅ Uploads coverage to Codecov (optional)
+
+## API Reference
+
+### Utilities
+
+### Store
+
+
+### Types
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure tests pass (`yarn test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Development Guidelines
+
+- Write tests for all new functionality
+- Maintain TypeScript strict mode compliance
+- Follow the existing code style
+- Update documentation as needed
+- Ensure CI passes before submitting PR
+
+## License
+
+MIT License - see LICENSE file for details.