@phystack/hub-client 4.5.19-dev → 4.5.20-dev

package/src/services/webrtc/types.ts

@@ -0,0 +1,273 @@
+/**
+ * WebRTC Type Definitions
+ *
+ * Contains all types for the WebRTC Manager system.
+ */
+
+// =============================================================================
+// Twin Messaging Interface (dependency injection)
+// =============================================================================
+
+/**
+ * Interface for twin messaging that the WebRTC system depends on.
+ * This allows the WebRTC system to be decoupled from PhyHubClient.
+ */
+export interface TwinMessagingInterface {
+  /** Send a message to a specific twin */
+  sendMessage(targetTwinId: string, data: any): Promise<void>;
+
+  /** Subscribe to receive messages from a twin */
+  subscribe(twinId: string): Promise<void>;
+
+  /** Register a callback for messages from a twin */
+  onMessage(twinId: string, callback: (msg: any) => void): void;
+
+  /** Unregister a callback for messages from a twin */
+  offMessage(twinId: string, callback: (msg: any) => void): void;
+
+  /** Get the ID of the local twin */
+  getOwnTwinId(): string;
+}
+
+// =============================================================================
+// WebRTC Manager Options
+// =============================================================================
+
+export interface WebRTCManagerOptions {
+  /** Enable verbose logging and additional events. Default: false */
+  verbose?: boolean;
+
+  /** Use STUN servers for NAT traversal. Default: true */
+  useStun?: boolean;
+
+  /** STUN server URLs. Default: Google's public STUN servers */
+  stunServers?: string[];
+
+  /** Connection timeout in milliseconds. Default: 15000 */
+  connectionTimeout?: number;
+
+  /** Initial retry delay in milliseconds. Default: 1000 */
+  initialRetryDelay?: number;
+
+  /** Maximum retry delay in milliseconds. Default: 30000 */
+  maxRetryDelay?: number;
+}
+
+export const DEFAULT_WEBRTC_OPTIONS: Required<WebRTCManagerOptions> = {
+  verbose: false,
+  useStun: true,
+  stunServers: ['stun:stun.l.google.com:19302', 'stun:stun1.l.google.com:19302'],
+  connectionTimeout: 15000,
+  initialRetryDelay: 1000,
+  maxRetryDelay: 30000,
+};
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/** Standard events (always available) */
+export type WebRTCStandardEvent = 'connected' | 'disconnected' | 'error';
+
+/** Verbose events (opt-in via options.verbose) */
+export type WebRTCVerboseEvent =
+  | 'reconnecting'
+  | 'reconnected'
+  | 'ice-state-change'
+  | 'signaling-state-change'
+  | 'ice-candidate';
+
+export type WebRTCEvent = WebRTCStandardEvent | WebRTCVerboseEvent;
+
+export interface WebRTCEventData {
+  connected: { targetTwinId: string; connectionType: 'datachannel' | 'mediastream' };
+  disconnected: { targetTwinId: string; connectionType: 'datachannel' | 'mediastream' };
+  error: { targetTwinId?: string; error: Error };
+  reconnecting: { targetTwinId: string; attempt: number };
+  reconnected: { targetTwinId: string; attempt: number };
+  'ice-state-change': { targetTwinId: string; state: RTCIceConnectionState };
+  'signaling-state-change': { targetTwinId: string; state: RTCSignalingState };
+  'ice-candidate': { targetTwinId: string; candidate: RTCIceCandidate | null };
+}
+
+export type WebRTCEventCallback<E extends WebRTCEvent = WebRTCEvent> = (
+  data: WebRTCEventData[E]
+) => void;
+
+// =============================================================================
+// DataChannel Types
+// =============================================================================
+
+/**
+ * Abstraction over RTCDataChannel that provides:
+ * - Automatic reconnection handling
+ * - Message buffering during reconnection
+ * - Simplified event API
+ */
+export interface PhygridDataChannel {
+  /** Send data through the channel. Accepts string, ArrayBuffer, or objects (auto-serialized to JSON) */
+  send(data: string | ArrayBuffer | object): void;
+
+  /** Register a callback for incoming messages */
+  onMessage(callback: (data: any) => void): void;
+
+  /** Unregister a message callback */
+  offMessage(callback: (data: any) => void): void;
+
+  /** Register a callback for channel close */
+  onClose(callback: () => void): void;
+
+  /** Unregister a close callback */
+  offClose(callback: () => void): void;
+
+  /** Close the data channel */
+  close(): void;
+
+  /** Check if the channel is currently open */
+  isOpen(): boolean;
+
+  /** Check if the channel is currently connecting/reconnecting */
+  isConnecting(): boolean;
+
+  /** Get the target twin ID this channel is connected to */
+  getTargetTwinId(): string;
+
+  /** Get the channel name (for multiple channels to same peer) */
+  getChannelName(): string;
+}
+
+// =============================================================================
+// MediaStream Types
+// =============================================================================
+
+/**
+ * Extended MediaStreamTrack with optional frame callback (Node.js @roamhq/wrtc)
+ */
+export interface ExtendedMediaStreamTrack extends MediaStreamTrack {
+  onFrame?: (frame: any) => void;
+}
+
+export interface MediaStreamOptions {
+  /** Direction for media. Default: 'recvonly' for initiator */
+  direction?: RTCRtpTransceiverDirection;
+
+  /** Local stream to send (for sendrecv or sendonly) */
+  localStream?: MediaStream;
+
+  /** Optional channel name for multiple streams to same peer (default: 'default') */
+  channelName?: string;
+}
+
+/**
+ * Abstraction over MediaStream that provides:
+ * - Automatic reconnection handling
+ * - Track lifecycle management
+ * - Frame activity monitoring
+ */
+export interface PhygridMediaStream {
+  /** Get all current tracks */
+  getTracks(): MediaStreamTrack[];
+
+  /** Get the underlying MediaStream object (for use as video srcObject) */
+  getStream(): MediaStream | null;
+
+  /** Add a track to send to the remote peer */
+  addTrack(track: MediaStreamTrack): void;
+
+  /** Register a callback for when a track is received */
+  onTrack(callback: (track: MediaStreamTrack) => void): void;
+
+  /** Unregister a track callback */
+  offTrack(callback: (track: MediaStreamTrack) => void): void;
+
+  /** Register a callback for frame data (if available, Node.js only) */
+  onFrame(callback: (frameData: any) => void): void;
+
+  /** Unregister a frame callback */
+  offFrame(callback: (frameData: any) => void): void;
+
+  /** Register a callback for stream close */
+  onClose(callback: () => void): void;
+
+  /** Unregister a close callback */
+  offClose(callback: () => void): void;
+
+  /** Close the media stream */
+  close(): void;
+
+  /** Check if the stream is currently receiving frames */
+  isReceivingFrames(): boolean;
+
+  /** Check if the stream is currently connecting or reconnecting */
+  isConnecting(): boolean;
+
+  /** Get the target twin ID this stream is connected to */
+  getTargetTwinId(): string;
+
+  /** Get the channel name (for multiple streams to same peer) */
+  getChannelName(): string;
+}
+
+// =============================================================================
+// Connection State Types
+// =============================================================================
+
+export type ConnectionType = 'datachannel' | 'mediastream';
+
+export interface ConnectionState {
+  targetTwinId: string;
+  connectionType: ConnectionType;
+  isInitiator: boolean;
+  pc: RTCPeerConnection | null;
+  isConnected: boolean;
+  isReconnecting: boolean;
+  reconnectAttempts: number;
+}
+
+// =============================================================================
+// Signaling Message Types
+// =============================================================================
+
+export type SignalingMessageType = 'offer' | 'answer' | 'ice';
+
+export interface SignalingMessage {
+  type: string; // Format: {channelPrefix}-{targetTwinId}:{messageType}
+  data: RTCSessionDescriptionInit | RTCIceCandidateInit;
+}
+
+// =============================================================================
+// Internal Types (for handler classes)
+// =============================================================================
+
+export interface PeerConnectionConfig {
+  targetTwinId: string;
+  isInitiator: boolean;
+  connectionType: ConnectionType;
+  channelPrefix: string;
+  useStun: boolean;
+  stunServers: string[];
+  onConnected: () => void;
+  onDisconnected: () => void;
+  onError: (error: Error) => void;
+  onReconnecting?: (attempt: number) => void;
+  onReconnected?: (attempt: number) => void;
+  onIceStateChange?: (state: RTCIceConnectionState) => void;
+  onSignalingStateChange?: (state: RTCSignalingState) => void;
+  onIceCandidate?: (candidate: RTCIceCandidate | null) => void;
+  // Called after peer connection is created but before offer is sent
+  // Use this to add data channels or media tracks that should be in the offer
+  onPeerConnectionCreated?: (pc: RTCPeerConnection) => void | Promise<void>;
+}
+
+export interface DataChannelConfig extends PeerConnectionConfig {
+  onMessage: (data: any) => void;
+  onOpen: () => void;
+  onClose: () => void;
+}
+
+export interface MediaStreamConfig extends PeerConnectionConfig {
+  direction: RTCRtpTransceiverDirection;
+  localStream?: MediaStream;
+  onTrack: (track: MediaStreamTrack) => void;
+  onFrameInactive?: () => void;
+}

package/src/services/webrtc/webrtc-globals.ts

@@ -0,0 +1,108 @@
+/**
+ * WebRTC Globals Initialization
+ *
+ * Single initialization point for WebRTC globals.
+ * Handles both browser and Node.js environments.
+ */
+
+// Track initialization state
+let isInitialized = false;
+let initializationPromise: Promise<void> | null = null;
+
+/**
+ * Ensures WebRTC globals are available in the current environment.
+ * In browsers, these are already available globally.
+ * In Node.js, we polyfill them from @roamhq/wrtc.
+ *
+ * This function is idempotent - safe to call multiple times.
+ */
+export async function ensureWebRTCGlobals(): Promise<void> {
+  // Already initialized
+  if (isInitialized) {
+    return;
+  }
+
+  // Initialization in progress - wait for it
+  if (initializationPromise) {
+    return initializationPromise;
+  }
+
+  initializationPromise = doInitialize();
+  await initializationPromise;
+}
+
+async function doInitialize(): Promise<void> {
+  // Browser environment - WebRTC is already available
+  if (typeof window !== 'undefined') {
+    if (typeof RTCPeerConnection === 'undefined') {
+      throw new Error('WebRTC is not supported in this browser');
+    }
+    isInitialized = true;
+    return;
+  }
+
+  // Node.js environment - need to polyfill
+  try {
+    const wrtc = require('@roamhq/wrtc');
+
+    if (typeof global.MediaStream === 'undefined' && wrtc.MediaStream) {
+      global.MediaStream = wrtc.MediaStream;
+    }
+
+    if (typeof (global as any).RTCDataChannel === 'undefined' && wrtc.RTCDataChannel) {
+      (global as any).RTCDataChannel = wrtc.RTCDataChannel;
+    }
+
+    if (typeof global.RTCPeerConnection === 'undefined' && wrtc.RTCPeerConnection) {
+      global.RTCPeerConnection = wrtc.RTCPeerConnection;
+    }
+
+    if (typeof global.RTCSessionDescription === 'undefined' && wrtc.RTCSessionDescription) {
+      global.RTCSessionDescription = wrtc.RTCSessionDescription;
+    }
+
+    if (typeof global.RTCIceCandidate === 'undefined' && wrtc.RTCIceCandidate) {
+      global.RTCIceCandidate = wrtc.RTCIceCandidate;
+    }
+
+    if (typeof (global as any).RTCVideoSource === 'undefined' && wrtc.nonstandard?.RTCVideoSource) {
+      (global as any).RTCVideoSource = wrtc.nonstandard.RTCVideoSource;
+    }
+
+    isInitialized = true;
+  } catch (error) {
+    throw new Error(
+      `Failed to initialize WebRTC in Node.js environment. ` +
+        `Ensure @roamhq/wrtc is installed: ${error}`
+    );
+  }
+}
+
+/**
+ * Check if WebRTC globals have been initialized.
+ */
+export function isWebRTCInitialized(): boolean {
+  return isInitialized;
+}
+
+/**
+ * Check if WebRTC is available in the current environment.
+ * Does not initialize - just checks availability.
+ */
+export function isWebRTCAvailable(): boolean {
+  if (typeof window !== 'undefined') {
+    return typeof RTCPeerConnection !== 'undefined';
+  }
+
+  // In Node.js, check if already initialized or if wrtc is available
+  if (isInitialized) {
+    return true;
+  }
+
+  try {
+    require.resolve('@roamhq/wrtc');
+    return true;
+  } catch {
+    return false;
+  }
+}