callway 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# Callway
+
+A lightweight, framework-agnostic WebRTC engine with pluggable signaling. Zero runtime dependencies; you bring your own signaling backend.
+
+## Overview
+
+- Mesh-ready multi-peer engine with perfect-negotiation-style collision handling.
+- Pluggable signaling adapters (interface-driven). Works with WebSocket, Firebase, Supabase, Redis, custom APIs, etc.
+- Optional React hooks.
+- TypeScript-first, ESM.
+- No bundled runtime deps.
+
+## Installation
+
+```bash
+npm install callway
+# optional React hooks
+npm install callway react
+```
+
+## Core API (quick start, vanilla JS style)
+
+```js
+import { PeerManager, MediaManager } from 'callway';
+import { SignalingAdapter } from 'callway/src/signaling/SignalingAdapter'; // interface shape
+
+// Minimal adapter (fill with your backend wiring: WebSocket/Firebase/etc.)
+const signaling = {
+  registerPeer(peerId, handler, roomId) {
+    // TODO: subscribe to your backend and call handler(message) on incoming
+  },
+  unregisterPeer(peerId) {},
+  async sendMessage(message) {
+    // TODO: send via your backend transport
+  },
+  cleanup() {}
+};
+
+const peerManager = new PeerManager('peer-a');
+const mediaManager = new MediaManager();
+peerManager.setSignalingAdapter(signaling, 'room-1');
+
+// Simple DOM helpers
+const remoteContainer = document.getElementById('remotes');
+function renderRemote(remoteId, stream) {
+  let video = remoteContainer.querySelector(`[data-peer="${remoteId}"]`);
+  if (!video) {
+    video = document.createElement('video');
+    video.setAttribute('data-peer', remoteId);
+    video.autoplay = true;
+    video.playsInline = true;
+    video.muted = false;
+    remoteContainer.appendChild(video);
+  }
+  video.srcObject = stream;
+}
+
+// Handle remote media
+peerManager.onRemoteStream((remoteStream, remoteId) => {
+  console.log('remote stream from', remoteId);
+  renderRemote(remoteId, remoteStream);
+});
+
+// Get local media, attach, and start call
+const localStream = await mediaManager.getUserMedia({ audio: true, video: true });
+document.getElementById('local').srcObject = localStream;
+
+// Add a peer and connect (assume peer-b exists on the same signaling backend)
+await peerManager.addPeer('peer-b');
+mediaManager.attachToPeer(peerManager, 'peer-b');
+await peerManager.createOffer('peer-b');
+```
+
+### Signaling adapter interface
+
+Implement to use any backend (WebSocket, Firebase, etc.):
+
+```ts
+import type { SignalingAdapter } from 'callway';
+
+interface SignalingAdapter {
+  registerPeer(peerId: string, handler: SignalingHandler, roomId?: string): void;
+  unregisterPeer(peerId: string): void;
+  sendMessage(message: SignalingMessage): Promise<void>;
+  broadcastToRoom?(from: string, roomId: string, messageType: string, data: any): Promise<void>;
+  cleanup(): void;
+}
+```
+
+### Swapping signaling backends
+
+- Custom backend: implement `SignalingAdapter` and pass to `peerManager.setSignalingAdapter(adapter, roomId?)`.
+- Example scaffolds (external; add deps yourself):
+  - `examples/FirebaseSignalingAdapter.ts`
+  - `examples/test-group-firebase.ts`
+
+### Multi-peer (mesh) usage tips
+
+- Each remote peer gets its own `RTCPeerConnection`.
+- Lower peerId initiates offers; higher peerId acts “polite” and rolls back on collisions.
+- ICE candidates are queued until remote descriptions are set; duplicates are ignored.
+
+### React usage (optional)
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import { PeerManager, MediaManager } from 'callway';
+import type { SignalingAdapter } from 'callway/src/signaling/SignalingAdapter';
+import { useIsCameraOff, useIsMicrophoneOff, useMediaState } from 'callway/react';
+
+// Your adapter
+class MySignalingAdapter implements SignalingAdapter {
+  registerPeer() {}
+  unregisterPeer() {}
+  async sendMessage() {}
+  cleanup() {}
+}
+
+export function CallApp() {
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const peerManager = useMemo(() => new PeerManager('peer-a'), []);
+  const mediaManager = useMemo(() => new MediaManager(), []);
+
+  useEffect(() => {
+    const adapter = new MySignalingAdapter();
+    peerManager.setSignalingAdapter(adapter, 'room-1');
+
+    peerManager.onRemoteStream((remote, id) => {
+      console.log('remote', id, remote);
+    });
+
+    mediaManager.getUserMedia({ audio: true, video: true })
+      .then((s) => {
+        setStream(s);
+        mediaManager.attachToPeer(peerManager, 'peer-b');
+        return peerManager.addPeer('peer-b');
+      })
+      .then(() => peerManager.createOffer('peer-b'))
+      .catch(console.error);
+
+    return () => {
+      peerManager.cleanup();
+      mediaManager.cleanup();
+      adapter.cleanup();
+    };
+  }, []);
+
+  const isCamOff = useIsCameraOff(stream);
+  const isMicOff = useIsMicrophoneOff(stream);
+  const state = useMediaState(stream);
+
+  return (
+    <div>
+      <div>Camera: {isCamOff ? 'Off' : 'On'}</div>
+      <div>Mic: {isMicOff ? 'Off' : 'On'}</div>
+      <div>Tracks: A{state.microphone.available ? 1 : 0} / V{state.camera.available ? 1 : 0}</div>
+    </div>
+  );
+}
+```
+
+## Production readiness
+
+- Core engine: dependency-free, ESM, TypeScript, mesh-ready with perfect negotiation, ICE queuing, and collision handling.
+- Signaling: pluggable; you must supply a production signaling adapter (WebSocket/Firebase/Supabase/custom).
+- Media: uses native WebRTC (getUserMedia/RTCPeerConnection). No media servers included.
+- Testing: use your own lightweight harness or the external examples; swap in your adapter for end-to-end testing.
+
+## License
+
+ISC
+

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+export { M as MediaState, g as getCameraTrack, c as getMediaState, b as getMicrophoneTrack, i as isCameraOff, a as isMicrophoneOff, o as observeMediaState } from './mediaUtils-5gVEq26H.js';
+
+/**
+ * SignalingAdapter - abstraction layer for signaling backends.
+ * Implement this interface for any backend (WebSocket, Firebase, custom API).
+ *
+ * The package remains dependency-free; adapters are user-provided.
+ */
+interface SignalingAdapter {
+    registerPeer(peerId: string, handler: SignalingHandler, roomId?: string): void;
+    unregisterPeer(peerId: string): void;
+    sendMessage(message: SignalingMessage): Promise<void>;
+    broadcastToRoom?(from: string, roomId: string, messageType: string, data: any): Promise<void>;
+    cleanup(): void;
+}
+
+/**
+ * PeerManager - Manages RTCPeerConnection instances for WebRTC calls
+ *
+ * Handles:
+ * - Creating and managing peer connections per remote participant
+ * - Creating offers and answers
+ * - Adding ICE candidates
+ * - Connection state management
+ *
+ * Supports both 1:1 and multi-peer/group calls.
+ * For 1:1 calls, use initialize() with a single remoteId.
+ * For group calls, use addPeer() to add multiple peers dynamically.
+ */
+interface PeerConnectionConfig {
+    iceServers?: RTCConfiguration['iceServers'];
+}
+interface SignalingMessage {
+    type: 'offer' | 'answer' | 'ice-candidate';
+    from: string;
+    to: string;
+    data: RTCSessionDescriptionInit | RTCIceCandidateInit;
+}
+type SignalingHandler = (message: SignalingMessage) => void | Promise<void>;
+declare class PeerManager {
+    private peerConnections;
+    private peerConnection;
+    private remoteId;
+    private localId;
+    private signalingHandler;
+    private signalingAdapter;
+    private registeredInAdapter;
+    private config;
+    private remoteStreamCallback;
+    private connectionStateCallback;
+    private iceConnectionStateCallback;
+    constructor(localId: string, config?: PeerConnectionConfig);
+    /**
+     * Set the signaling handler for sending messages
+     */
+    setSignalingHandler(handler: SignalingHandler): void;
+    /**
+     * Set a signaling adapter. This will register this peer and wire sending.
+     */
+    setSignalingAdapter(adapter: SignalingAdapter, roomId?: string): void;
+    /**
+     * Create a new peer connection for a specific remote peer
+     */
+    private createPeerConnection;
+    /**
+     * Initialize peer connection for a call (1:1 compatibility)
+     * For multi-peer calls, use addPeer() instead
+     */
+    initialize(remoteId: string): Promise<void>;
+    /**
+     * Add a new peer to the room (multi-peer support)
+     * Creates a new RTCPeerConnection for this peer
+     */
+    addPeer(remoteId: string, isInitiator?: boolean): Promise<void>;
+    /**
+     * Remove a peer from the room
+     */
+    removePeer(remoteId: string): Promise<void>;
+    /**
+     * Get all remote peer IDs
+     */
+    getRemotePeerIds(): string[];
+    /**
+     * Check if a peer exists
+     */
+    hasPeer(remoteId: string): boolean;
+    /**
+     * Get peer connection for a specific remote peer (multi-peer support)
+     */
+    getPeerConnectionFor(remoteId: string): RTCPeerConnection | null;
+    /**
+     * Create an offer for a specific peer (caller side)
+     */
+    createOffer(remoteId: string): Promise<RTCSessionDescriptionInit>;
+    /**
+     * Create offers for all peers (multi-peer support)
+     */
+    createOffersForAll(): Promise<void>;
+    /**
+     * Handle incoming offer from a peer (callee side)
+     *
+     * Collision strategy: the peer who already has a local offer ignores the
+     * incoming offer (impolite); with deterministic initiator selection in the
+     * caller, collisions should be rare. This keeps the signaling state valid.
+     */
+    handleOffer(offer: RTCSessionDescriptionInit, remoteId: string): Promise<RTCSessionDescriptionInit | null>;
+    /**
+     * Handle incoming answer from a peer (caller side)
+     */
+    handleAnswer(answer: RTCSessionDescriptionInit, remoteId: string): Promise<void>;
+    /**
+     * Process queued ICE candidates for a peer
+     */
+    private processIceCandidateQueue;
+    /**
+     * Add ICE candidate for a specific peer
+     * Queues candidates if remote description is not set yet
+     */
+    addIceCandidate(candidate: RTCIceCandidateInit, remoteId: string): Promise<void>;
+    /**
+     * Add a media track to a specific peer connection
+     */
+    addTrack(track: MediaStreamTrack, stream: MediaStream, remoteId?: string): void;
+    /**
+     * Add media tracks to all peer connections (multi-peer support)
+     */
+    addTrackToAll(track: MediaStreamTrack, stream: MediaStream): void;
+    /**
+     * Get the remote media stream for a specific peer
+     */
+    getRemoteStream(remoteId: string): MediaStream | null;
+    /**
+     * Set handler for when remote stream is available
+     * Callback receives (stream, remoteId) for multi-peer support
+     * Can be called before or after initialization
+     */
+    onRemoteStream(callback: (stream: MediaStream, remoteId: string) => void): void;
+    /**
+     * Set handler for connection state changes
+     * Callback receives (state, remoteId) for multi-peer support
+     */
+    onConnectionStateChange(callback: (state: RTCPeerConnectionState, remoteId: string) => void): void;
+    /**
+     * Set handler for ICE connection state changes
+     * Callback receives (state, remoteId) for multi-peer support
+     */
+    onIceConnectionStateChange(callback: (state: RTCIceConnectionState, remoteId: string) => void): void;
+    /**
+     * Get the peer connection instance (legacy 1:1 support)
+     */
+    getPeerConnection(): RTCPeerConnection | null;
+    /**
+     * Cleanup and close all peer connections
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * MediaManager - Manages local media streams (getUserMedia)
+ *
+ * Handles:
+ * - Requesting user media (audio/video)
+ * - Managing local media streams
+ * - Attaching streams to peer connections
+ *
+ * Currently supports single stream management.
+ * TODO: Extend for multiple streams or screen sharing in the future.
+ */
+interface MediaConstraints {
+    audio?: boolean | MediaTrackConstraints;
+    video?: boolean | MediaTrackConstraints;
+}
+declare class MediaManager {
+    private localStream;
+    /**
+     * Request user media (audio and/or video)
+     */
+    getUserMedia(constraints?: MediaConstraints): Promise<MediaStream>;
+    /**
+     * Get the current local stream
+     */
+    getLocalStream(): MediaStream | null;
+    /**
+     * Stop all tracks in the local stream
+     */
+    stopLocalStream(): void;
+    /**
+     * Attach local stream to a peer connection (1:1 or specific peer)
+     * This adds all tracks from the local stream to the peer connection
+     */
+    attachToPeer(peerManager: PeerManager, remoteId?: string): void;
+    /**
+     * Attach local stream to all peers in a room (multi-peer support)
+     * This adds all tracks from the local stream to all peer connections
+     */
+    attachToAllPeers(peerManager: PeerManager): void;
+    /**
+     * Check if camera (video) is off/muted
+     * Returns true if camera is off, false if on
+     */
+    isCameraOff(): boolean;
+    /**
+     * Check if microphone (audio) is off/muted
+     * Returns true if microphone is off, false if on
+     */
+    isMicrophoneOff(): boolean;
+    /**
+     * Get camera track state
+     * Returns the first video track or null
+     */
+    getCameraTrack(): MediaStreamTrack | null;
+    /**
+     * Get microphone track state
+     * Returns the first audio track or null
+     */
+    getMicrophoneTrack(): MediaStreamTrack | null;
+    /**
+     * Get detailed media state information
+     */
+    getMediaState(): {
+        hasStream: boolean;
+        camera: {
+            available: boolean;
+            enabled: boolean;
+            muted: boolean;
+            readyState: MediaStreamTrackState | null;
+        };
+        microphone: {
+            available: boolean;
+            enabled: boolean;
+            muted: boolean;
+            readyState: MediaStreamTrackState | null;
+        };
+    };
+    /**
+     * Cleanup - stop all tracks
+     */
+    cleanup(): void;
+}
+
+export { type MediaConstraints, MediaManager, type PeerConnectionConfig, PeerManager, type SignalingAdapter, type SignalingHandler, type SignalingMessage };