@enfin/chat 1.2.0

package/README.md

@@ -0,0 +1,224 @@
+# @enfin/chat
+
+React frontend SDK for chat platform — components, hooks, and context provider.
+
+## Install
+
+```bash
+npm install @enfin/chat react react-dom socket.io-client
+```
+
+## Quick Start
+
+### 1. Wrap Your App with ChatProvider
+
+```tsx
+import { ChatProvider } from '@enfin/chat';
+import Chat from '@enfin/chat';
+
+function App() {
+  return (
+    <ChatProvider
+      config={{ apiKey: 'chat_xxx' }}
+      userId="user_123"
+      userName="Alice"
+      serverUrl="http://localhost:3002"
+    >
+      <Chat />
+    </ChatProvider>
+  );
+}
+```
+
+Pass `serverUrl` as your chat-server URL. It connects to `${serverUrl}/chat` namespace and calls REST at `${serverUrl}/api/*`.
+
+## ChatProvider Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `ChatConfig` | Yes | `{ apiKey: string }` |
+| `userId` | string | Yes | Unique user ID |
+| `userName` | string | Yes | Display name |
+| `serverUrl` | string | Yes | Your chat-server URL |
+
+### ChatConfig
+
+```ts
+interface ChatConfig {
+  apiKey: string;
+  validationUrl?: string;  // optional custom validation endpoint
+  ringtoneUrl?: string;    // optional override for the incoming-call ringtone
+}
+```
+
+#### `ringtoneUrl` — custom incoming-call ringtone
+
+By default the SDK plays a bundled `i_phone_message.mp3` whenever an audio call comes in. Pass `ringtoneUrl` to override it with your own file. Works with absolute URLs or any path the consumer's bundler/dev server can resolve.
+
+```tsx
+<ChatProvider
+  config={{
+    apiKey: 'chat_xxx',
+    ringtoneUrl: '/sounds/my-ring.mp3',   // served by your app
+  }}
+  userId="user_123"
+  userName="Alice"
+  serverUrl="http://localhost:3002"
+>
+```
+
+- Anything that HTML5 `<audio>` accepts works: `/sounds/ring.mp3`, `https://cdn.example.com/ring.ogg`, or a Vite/Webpack `import` resolved URL.
+- If the override URL fails to load, the browser console logs `[RINGTONE] play() rejected: ...` and the call UI keeps working.
+- The default mp3 is bundled at `dist/public/music/i_phone_message.mp3` and shipped with the package — no extra setup needed.
+
+## Default Chat Component
+
+The `<Chat />` component provides full UI:
+
+- User registration/login
+- Room list (direct and group)
+- Real-time messaging
+- File uploads with drag-and-drop
+- Typing indicators
+- Online presence (green dot)
+- Audio calls (WebRTC)
+
+### Customize Appearance
+
+Styles are in `styles.css`. Override CSS variables:
+
+```css
+:root {
+  --chat-primary: #007bff;
+  --chat-bg: #ffffff;
+  --chat-text: #333333;
+  --chat-border: #e0e0e0;
+  --chat-radius: 8px;
+  --chat-font: system-ui, sans-serif;
+}
+```
+
+## Build Custom UI
+
+Use hooks instead of `<Chat />`:
+
+```tsx
+import { useChatContext, useRooms, useMessages, useCall, useSocket } from '@enfin/chat';
+import { ChatProvider } from '@enfin/chat';
+
+function CustomChat() {
+  const { userId, messages, rooms, currentRoom, sendMessage, selectRoom } = useChatContext();
+  const { activeCall, startCall, endCall, acceptCall } = useCall();
+
+  // Send message
+  await sendMessage(currentRoom._id, 'Hello!');
+
+  // Start call
+  await startCall(currentRoom._id, 'participant_456');
+}
+```
+
+### useChatContext
+
+Returns everything:
+
+```ts
+interface ChatContextValue {
+  userId: string;
+  userName: string;
+  messages: Message[];
+  rooms: Room[];
+  users: ChatUser[];
+  currentRoom?: Room;
+  activeCall?: AudioCall;
+  typingUsers: PresenceStatus[];
+  connected: boolean;
+  loading: boolean;
+  error?: string;
+  sendMessage: (roomId, content, file?) => Promise<void>;
+  selectRoom: (roomId) => void;
+  createRoom: (name, type, members) => Promise<Room>;
+  startCall: (roomId, participantId) => Promise<void>;
+  endCall: () => Promise<void>;
+  acceptCall: () => Promise<void>;
+  mute: () => void;
+  unmute: () => void;
+  isMuted: boolean;
+  socket?: Socket;
+  refreshUsers: () => Promise<void>;
+}
+```
+
+### useRooms
+
+```ts
+const { rooms, loading, error, createRoom, openDirectRoom } = useRooms();
+```
+
+### useMessages
+
+```ts
+const { messages, loading, sendMessage, markRead } = useMessages(roomId);
+```
+
+### useCall
+
+```ts
+const { activeCall, startCall, endCall, acceptCall, mute, unmute, isMuted } = useCall();
+```
+
+### useSocket
+
+Raw Socket.IO access:
+
+```ts
+const socket = useSocket();
+// socket.emit('message', { roomId, content });
+// socket.on('message', (msg) => { ... });
+```
+
+## Types
+
+All types are exported:
+
+```ts
+import { Message, Room, User, ChatConfig } from '@enfin/chat';
+```
+
+## Environment Variables
+
+### Vite
+
+```env
+VITE_CHAT_API_KEY=chat_xxx
+VITE_SERVER_URL=http://localhost:3002
+```
+
+### CRA
+
+```env
+REACT_APP_CHAT_API_KEY=chat_xxx
+REACT_APP_SERVER_URL=http://localhost:3002
+```
+
+### Next.js
+
+In `.env.local`:
+
+```env
+NEXT_PUBLIC_CHAT_API_KEY=chat_xxx
+NEXT_PUBLIC_SERVER_URL=http://localhost:3002
+```
+
+Then access via `process.env.NEXT_PUBLIC_*`.
+
+## Server Requirement
+
+Your backend must run `@enfin/chat-server`. The frontend SDK communicates with it via:
+
+- Socket.IO: `${serverUrl}/chat`
+- REST: `${serverUrl}/api/*`
+
+---
+
+For backend server, see `@enfin/chat-server`.

package/dist/call/WebRTCManager.d.ts

@@ -0,0 +1,54 @@
+import { WebRTCConfig, SignalPayload } from './types';
+export type WebRTCManagerState = 'idle' | 'requesting-media' | 'connecting' | 'connected' | 'failed' | 'closed';
+export interface WebRTCManagerCallbacks {
+    sendSignal: (payload: SignalPayload) => void;
+    onStateChange?: (state: WebRTCManagerState) => void;
+    onRemoteStream?: (stream: MediaStream) => void;
+    onLocalStream?: (stream: MediaStream) => void;
+    onError?: (err: Error) => void;
+}
+export declare class WebRTCManager {
+    private pc;
+    private localStream;
+    private remoteStream;
+    private state;
+    private config;
+    private callbacks;
+    private isInitiator;
+    private currentRoomId;
+    private hasReceivedRemote;
+    private pendingOffer;
+    private bufferedOffer;
+    private pendingIceCandidates;
+    private isCallee;
+    private isAccepted;
+    constructor(config: WebRTCConfig, callbacks: WebRTCManagerCallbacks);
+    setSignalEmitter(sendSignal: (payload: import('./types').SignalPayload) => void): void;
+    getState(): WebRTCManagerState;
+    getRemoteStream(): MediaStream | null;
+    getLocalStream(): MediaStream | null;
+    private setState;
+    private buildPeerConnection;
+    startAsCaller(roomId: string): Promise<void>;
+    /**
+     * Sends the buffered offer + flushes any pending ICE candidates.
+     * Call this AFTER the server has confirmed the call record exists,
+     * so the callee is ready to receive `call:signal` events.
+     */
+    sendOffer(): Promise<void>;
+    handleOffer(offerSdp: string, roomId: string): Promise<void>;
+    private flushPendingIce;
+    handleAnswer(answerSdp: string): Promise<void>;
+    handleIceCandidate(candidate: string, sdpMid: string | null, sdpMLineIndex: number): Promise<void>;
+    acquireLocalStream(): Promise<MediaStream>;
+    setMuted(muted: boolean): void;
+    processPendingOffer(): Promise<void>;
+    /**
+     * Mark this manager as a callee (it received the offer via call:incoming,
+     * not via startCall). While not yet accepted, incoming offers are buffered
+     * so we don't request mic / open PC before the user clicks Accept.
+     */
+    markAsCallee(): void;
+    markAsAccepted(): void;
+    close(): void;
+}

package/dist/call/WebRTCManager.js

@@ -0,0 +1,274 @@
+import { DEFAULT_WEBRTC_CONFIG } from './types';
+export class WebRTCManager {
+    constructor(config, callbacks) {
+        this.pc = null;
+        this.localStream = null;
+        this.remoteStream = null;
+        this.state = 'idle';
+        this.isInitiator = false;
+        this.currentRoomId = null;
+        this.hasReceivedRemote = false;
+        this.pendingOffer = null;
+        this.bufferedOffer = null;
+        this.pendingIceCandidates = [];
+        this.isCallee = false;
+        this.isAccepted = false;
+        this.config = { ...DEFAULT_WEBRTC_CONFIG, ...config };
+        this.callbacks = callbacks;
+    }
+    setSignalEmitter(sendSignal) {
+        this.callbacks = { ...this.callbacks, sendSignal };
+    }
+    getState() {
+        return this.state;
+    }
+    getRemoteStream() {
+        return this.remoteStream;
+    }
+    getLocalStream() {
+        return this.localStream;
+    }
+    setState(next) {
+        this.state = next;
+        this.callbacks.onStateChange?.(next);
+    }
+    buildPeerConnection() {
+        const pc = new RTCPeerConnection({
+            iceServers: this.config.iceServers,
+            iceTransportPolicy: this.config.iceTransportPolicy
+        });
+        pc.onicecandidate = (event) => {
+            if (event.candidate && this.currentRoomId) {
+                this.callbacks.sendSignal({
+                    type: 'ice-candidate',
+                    candidate: event.candidate.candidate,
+                    sdpMid: event.candidate.sdpMid,
+                    sdpMLineIndex: event.candidate.sdpMLineIndex,
+                    roomId: this.currentRoomId
+                });
+            }
+        };
+        pc.ontrack = (event) => {
+            // Chrome fires ontrack for locally added tracks too (the transceiver
+            // emits a track event for the sender's stream). Filter those out so
+            // the audio element only ever plays the REMOTE peer's stream.
+            if (event.transceiver && event.transceiver.direction === 'sendonly') {
+                return;
+            }
+            // Also reject the event if every stream is actually our own local stream.
+            const remoteStream = event.streams.find(s => s !== this.localStream) || event.streams[0];
+            if (remoteStream && remoteStream !== this.localStream) {
+                this.remoteStream = remoteStream;
+                this.hasReceivedRemote = true;
+                this.callbacks.onRemoteStream?.(remoteStream);
+                this.setState('connected');
+            }
+        };
+        pc.onconnectionstatechange = () => {
+            const s = pc.connectionState;
+            if (s === 'connected')
+                this.setState('connected');
+            else if (s === 'failed')
+                this.setState('failed');
+            else if (s === 'closed')
+                this.setState('closed');
+            else if (s === 'connecting')
+                this.setState('connecting');
+        };
+        pc.oniceconnectionstatechange = () => {
+            const s = pc.iceConnectionState;
+            if (s === 'connected' || s === 'completed')
+                this.setState('connected');
+            else if (s === 'failed')
+                this.setState('failed');
+        };
+        return pc;
+    }
+    async startAsCaller(roomId) {
+        if (this.state !== 'idle' && this.state !== 'closed') {
+            return;
+        }
+        this.isInitiator = true;
+        this.currentRoomId = roomId;
+        this.hasReceivedRemote = false;
+        this.setState('requesting-media');
+        try {
+            await this.acquireLocalStream();
+            const pc = this.buildPeerConnection();
+            this.localStream.getTracks().forEach(track => {
+                pc.addTrack(track, this.localStream);
+            });
+            this.pc = pc;
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+            // Buffer the offer — don't send yet. The caller (startCall) will
+            // invoke sendOffer() after the server confirms the call exists.
+            this.bufferedOffer = { sdp: offer.sdp, roomId };
+            this.setState('connecting');
+        }
+        catch (err) {
+            this.setState('failed');
+            this.callbacks.onError?.(err);
+            throw err;
+        }
+    }
+    /**
+     * Sends the buffered offer + flushes any pending ICE candidates.
+     * Call this AFTER the server has confirmed the call record exists,
+     * so the callee is ready to receive `call:signal` events.
+     */
+    async sendOffer() {
+        if (!this.bufferedOffer || !this.pc)
+            return;
+        const { sdp, roomId } = this.bufferedOffer;
+        this.callbacks.sendSignal({
+            type: 'offer',
+            sdp,
+            roomId
+        });
+        this.bufferedOffer = null;
+        // Flush any ICE candidates that arrived before the offer was sent
+        await this.flushPendingIce();
+    }
+    async handleOffer(offerSdp, roomId) {
+        // Callee: always buffer the offer until the user accepts the call.
+        // We don't want to request mic / open PC before the user clicks Accept.
+        if (this.isCallee && !this.isAccepted) {
+            this.pendingOffer = { sdp: offerSdp, roomId };
+            return;
+        }
+        if (this.state !== 'idle' && this.state !== 'closed') {
+            // Already in a call or call in progress - buffer the offer
+            if (this.isInitiator)
+                return; // initiator ignores incoming offers
+            this.pendingOffer = { sdp: offerSdp, roomId };
+            return;
+        }
+        this.isInitiator = false;
+        this.currentRoomId = roomId;
+        this.hasReceivedRemote = false;
+        this.setState('requesting-media');
+        try {
+            await this.acquireLocalStream();
+            const pc = this.buildPeerConnection();
+            this.localStream.getTracks().forEach(track => {
+                pc.addTrack(track, this.localStream);
+            });
+            this.pc = pc;
+            await pc.setRemoteDescription(new RTCSessionDescription({ type: 'offer', sdp: offerSdp }));
+            const answer = await pc.createAnswer();
+            await pc.setLocalDescription(answer);
+            this.callbacks.sendSignal({
+                type: 'answer',
+                sdp: answer.sdp,
+                roomId
+            });
+            this.setState('connecting');
+            // Flush buffered ICE candidates
+            await this.flushPendingIce();
+        }
+        catch (err) {
+            this.setState('failed');
+            this.callbacks.onError?.(err);
+            throw err;
+        }
+    }
+    async flushPendingIce() {
+        if (!this.pc)
+            return;
+        for (const c of this.pendingIceCandidates) {
+            try {
+                await this.pc.addIceCandidate(new RTCIceCandidate(c));
+            }
+            catch { /* benign */ }
+        }
+        this.pendingIceCandidates = [];
+    }
+    async handleAnswer(answerSdp) {
+        if (!this.pc)
+            return;
+        if (this.pc.signalingState !== 'have-local-offer') {
+            return;
+        }
+        await this.pc.setRemoteDescription(new RTCSessionDescription({ type: 'answer', sdp: answerSdp }));
+    }
+    async handleIceCandidate(candidate, sdpMid, sdpMLineIndex) {
+        if (!this.pc) {
+            // Buffer until PC exists
+            this.pendingIceCandidates.push({ candidate, sdpMid, sdpMLineIndex });
+            return;
+        }
+        try {
+            await this.pc.addIceCandidate(new RTCIceCandidate({
+                candidate,
+                sdpMid,
+                sdpMLineIndex
+            }));
+        }
+        catch (err) {
+            // Common benign failure: candidate arrives after PC closed
+            if (this.pc.connectionState !== 'closed') {
+                this.callbacks.onError?.(err);
+            }
+        }
+    }
+    async acquireLocalStream() {
+        if (this.localStream)
+            return this.localStream;
+        this.localStream = await navigator.mediaDevices.getUserMedia({
+            audio: this.config.audioConstraints
+        });
+        this.callbacks.onLocalStream?.(this.localStream);
+        return this.localStream;
+    }
+    setMuted(muted) {
+        if (!this.localStream)
+            return;
+        this.localStream.getAudioTracks().forEach(track => {
+            track.enabled = !muted;
+        });
+    }
+    async processPendingOffer() {
+        if (!this.pendingOffer)
+            return;
+        const { sdp, roomId } = this.pendingOffer;
+        this.pendingOffer = null;
+        this.isAccepted = true;
+        await this.handleOffer(sdp, roomId);
+    }
+    /**
+     * Mark this manager as a callee (it received the offer via call:incoming,
+     * not via startCall). While not yet accepted, incoming offers are buffered
+     * so we don't request mic / open PC before the user clicks Accept.
+     */
+    markAsCallee() {
+        this.isCallee = true;
+        this.isAccepted = false;
+    }
+    markAsAccepted() {
+        this.isAccepted = true;
+    }
+    close() {
+        if (this.localStream && this.localStream.getTracks) {
+            this.localStream.getTracks().forEach(track => track.stop());
+            this.localStream = null;
+        }
+        if (this.pc) {
+            try {
+                this.pc.close();
+            }
+            catch { /* noop */ }
+            this.pc = null;
+        }
+        this.remoteStream = null;
+        this.isInitiator = false;
+        this.currentRoomId = null;
+        this.hasReceivedRemote = false;
+        this.pendingOffer = null;
+        this.bufferedOffer = null;
+        this.pendingIceCandidates = [];
+        this.isCallee = false;
+        this.isAccepted = false;
+        this.setState('closed');
+    }
+}

package/dist/call/signaling.d.ts

@@ -0,0 +1,3 @@
+import type { Socket } from 'socket.io-client';
+import type { WebRTCManager } from './WebRTCManager';
+export declare function attachSignaling(socket: Socket, manager: WebRTCManager): () => void;

package/dist/call/signaling.js

@@ -0,0 +1,24 @@
+export function attachSignaling(socket, manager) {
+    const onSignal = (payload) => {
+        if (!payload || !payload.type || !payload.roomId)
+            return;
+        switch (payload.type) {
+            case 'offer':
+                manager.handleOffer(payload.sdp, payload.roomId).catch(() => { });
+                break;
+            case 'answer':
+                manager.handleAnswer(payload.sdp).catch(() => { });
+                break;
+            case 'ice-candidate':
+                manager.handleIceCandidate(payload.candidate, payload.sdpMid, payload.sdpMLineIndex).catch(() => { });
+                break;
+        }
+    };
+    manager.setSignalEmitter((payload) => {
+        socket.emit('call:signal', payload);
+    });
+    socket.on('call:signal', onSignal);
+    return () => {
+        socket.off('call:signal', onSignal);
+    };
+}

package/dist/call/types.d.ts

@@ -0,0 +1,25 @@
+export type SignalType = 'offer' | 'answer' | 'ice-candidate';
+export interface SignalOffer {
+    type: 'offer';
+    sdp: string;
+    roomId: string;
+}
+export interface SignalAnswer {
+    type: 'answer';
+    sdp: string;
+    roomId: string;
+}
+export interface SignalIceCandidate {
+    type: 'ice-candidate';
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number;
+    roomId: string;
+}
+export type SignalPayload = SignalOffer | SignalAnswer | SignalIceCandidate;
+export interface WebRTCConfig {
+    iceServers?: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    audioConstraints?: MediaTrackConstraints;
+}
+export declare const DEFAULT_WEBRTC_CONFIG: Required<WebRTCConfig>;

package/dist/call/types.js

@@ -0,0 +1,13 @@
+// WebRTC Signaling Types for audio calls
+export const DEFAULT_WEBRTC_CONFIG = {
+    iceServers: [
+        { urls: 'stun:stun.l.google.com:19302' },
+        { urls: 'stun:stun1.l.google.com:19302' }
+    ],
+    iceTransportPolicy: 'all',
+    audioConstraints: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true
+    }
+};

package/dist/components/Chat.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface ChatProps {
+    theme?: 'light' | 'dark';
+}
+/**
+ * Default Chat Component
+ *
+ * Two-pane layout:
+ * - Top: app header with current user (avatar, name, switch button)
+ * - Left: list of registered users (click to select a peer)
+ * - Right: messages + input area for the selected peer
+ */
+export declare function Chat({ theme }: ChatProps): React.JSX.Element;
+export default Chat;