vg-x07df 0.1.0

package/packages/sdk/src/hooks/useEvent.ts

@@ -0,0 +1,188 @@
+import { useEffect, useRef, useState } from "react";
+import { eventBus } from "../core/events";
+import { SdkEventType } from "../core/events/types";
+import type { EventFilter, EventHandler, SdkEvent } from "../core/events/types";
+
+/**
+ * Hook for subscribing to SDK events
+ *
+ * @example
+ * // Listen for specific event type
+ * const callEvent = useEvent(SdkEventType.CALL_ACCEPTED);
+ *
+ * @example
+ * // Listen with callback
+ * useEvent(SdkEventType.MEDIA_ENABLED, (event) => {
+ *   // Handle media enabled event
+ * });
+ *
+ * @example
+ * // Listen to pattern with filter
+ * useEvent('call:*', null, (event) => event.payload.callId === 'specific-call');
+ */
+export function useEvent<T = any>(
+  eventType: string | SdkEventType,
+  callback?: EventHandler<T> | null,
+  filter?: EventFilter<T>
+): SdkEvent<T> | undefined {
+  const [lastEvent, setLastEvent] = useState<SdkEvent<T> | undefined>(
+    undefined
+  );
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    const handler: EventHandler<T> = (event: SdkEvent<T>) => {
+      setLastEvent(event);
+      if (callbackRef.current) {
+        callbackRef.current(event);
+      }
+    };
+
+    // Support pattern matching (e.g., "call:*")
+    const subscription = eventType.includes("*")
+      ? eventBus.onPattern(eventType, handler, filter)
+      : eventBus.on(eventType, handler, filter);
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [eventType, filter]);
+
+  return lastEvent;
+}
+
+/**
+ * Hook for subscribing to events once
+ *
+ * @example
+ * useEventOnce(SdkEventType.CALL_ACCEPTED, (event) => {
+ *   // Handle call accepted event once
+ * });
+ */
+export function useEventOnce<T = any>(
+  eventType: string | SdkEventType,
+  callback: EventHandler<T>,
+  filter?: EventFilter<T>
+): void {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    const subscription = eventBus.once(eventType, callbackRef.current, filter);
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [eventType, filter]);
+}
+
+/**
+ * Hook for accessing the event bus directly
+ * Use this for advanced event management scenarios
+ *
+ * @example
+ * const events = useEventBus();
+ *
+ * // Emit custom event
+ * events.emit('custom:event', { data: 'test' });
+ *
+ * // Get event history
+ * const history = events.getEventHistory();
+ */
+export function useEventBus() {
+  return eventBus;
+}
+
+/**
+ * Hook for getting events matching a condition
+ *
+ * @example
+ * const callEvents = useEventHistory((event) =>
+ *   event.type.startsWith('call:') &&
+ *   event.payload.callId === currentCallId
+ * );
+ */
+export function useEventHistory<T = any>(
+  filter?: EventFilter<T>
+): SdkEvent<T>[] {
+  const [events, setEvents] = useState<SdkEvent<T>[]>(() =>
+    filter ? eventBus.getEventsWhere(filter) : eventBus.getEventHistory()
+  );
+
+  useEffect(() => {
+    const updateEvents = () => {
+      const newEvents = filter
+        ? eventBus.getEventsWhere(filter)
+        : eventBus.getEventHistory();
+      setEvents(newEvents);
+    };
+
+    // Subscribe to any event to trigger updates
+    const subscription = eventBus.onPattern("*", updateEvents);
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [filter]);
+
+  return events;
+}
+
+/**
+ * Hook for consuming call-specific events
+ * Automatically filters events by call ID
+ *
+ * @example
+ * const { callAccepted, callDeclined, participantJoined } = useCallEvents(callId);
+ */
+export function useCallEvents(callId?: string) {
+  const callFilter: EventFilter = (event) =>
+    !callId || event.payload?.callId === callId;
+
+  const callAccepted = useEvent(SdkEventType.CALL_ACCEPTED, null, callFilter);
+  const callDeclined = useEvent(SdkEventType.CALL_DECLINED, null, callFilter);
+  const callEnded = useEvent(SdkEventType.CALL_ENDED, null, callFilter);
+  const participantJoined = useEvent(
+    SdkEventType.PARTICIPANT_JOINED,
+    null,
+    callFilter
+  );
+  const participantLeft = useEvent(
+    SdkEventType.PARTICIPANT_LEFT,
+    null,
+    callFilter
+  );
+
+  return {
+    callAccepted,
+    callDeclined,
+    callEnded,
+    participantJoined,
+    participantLeft,
+  };
+}
+
+/**
+ * Hook for consuming media events
+ * Automatically filters events by participant ID
+ *
+ * @example
+ * const { mediaEnabled, mediaDisabled } = useMediaEvents(participantId);
+ */
+export function useMediaEvents(participantId?: string) {
+  const mediaFilter: EventFilter = (event) =>
+    !participantId || event.payload?.participantId === participantId;
+
+  const mediaEnabled = useEvent(SdkEventType.MEDIA_ENABLED, null, mediaFilter);
+  const mediaDisabled = useEvent(
+    SdkEventType.MEDIA_DISABLED,
+    null,
+    mediaFilter
+  );
+
+  return {
+    mediaEnabled,
+    mediaDisabled,
+  };
+}

package/packages/sdk/src/hooks/useMediaControls.ts

@@ -0,0 +1,215 @@
+import { useState } from "react";
+import type { MediaActions } from "../livekit";
+import { useSdk } from "../provider/RtcProvider";
+import { useRtcStore } from "../state/store";
+import type { RtcError } from "../state/types";
+import { createLogger } from "../utils/logger";
+import { useDevices } from "./useDevices";
+
+const logger = createLogger("hooks:media-controls");
+
+export interface MediaControlsState {
+  isVideoEnabled: boolean;
+  isAudioEnabled: boolean;
+  isCameraAvailable: boolean;
+  isMicrophoneAvailable: boolean;
+  isConnected: boolean;
+  isLoading: boolean;
+  errors: RtcError[];
+}
+
+export interface EnhancedMediaActions {
+  enableCamera: () => Promise<void>;
+  disableCamera: () => Promise<void>;
+  enableMicrophone: () => Promise<void>;
+  disableMicrophone: () => Promise<void>;
+  toggleCamera: () => Promise<void>;
+  toggleMicrophone: () => Promise<void>;
+  // Device switching
+  switchCamera: (deviceId: string) => Promise<void>;
+  switchMicrophone: (deviceId: string) => Promise<void>;
+  // Simple aliases
+  toggleAudio: () => Promise<void>;
+  toggleVideo: () => Promise<void>;
+}
+
+export interface MediaControlsHook
+  extends MediaControlsState,
+    EnhancedMediaActions {}
+
+export function useMediaControls(): MediaControlsHook & {
+  devices: {
+    cameras: any[];
+    microphones: any[];
+    speakers: any[];
+  };
+} {
+  const sdk = useSdk();
+  const local = useRtcStore((state) => state.local);
+  const connection = useRtcStore((state) => state.connection);
+  const errors = useRtcStore((state) =>
+    state.errors.filter(
+      (e) =>
+        e.code.startsWith("CAMERA_") ||
+        e.code.startsWith("MICROPHONE_") ||
+        e.code.startsWith("LIVEKIT_")
+    )
+  );
+  const devices = useDevices();
+
+  const [isLoading, setIsLoading] = useState(false);
+
+  // Check if media controls are available and connected
+  const isConnected = connection.connected;
+  let mediaControls: MediaActions | null = null;
+
+  try {
+    if (sdk.livekit && isConnected) {
+      mediaControls = sdk.livekit.media;
+    }
+  } catch {
+    // Media controls not available - room not connected
+    mediaControls = null;
+  }
+
+  // Enhanced wrapper functions with loading states and better error handling
+  const createEnhancedAction = (
+    action: () => Promise<void>,
+    actionName: string
+  ) => {
+    return async (): Promise<void> => {
+      if (!mediaControls) {
+        const errorMsg = !isConnected
+          ? "Cannot control media - not connected to LiveKit room"
+          : "Media controls not available - LiveKit service not initialized";
+        throw new Error(errorMsg);
+      }
+
+      setIsLoading(true);
+      try {
+        await action();
+      } catch (error) {
+        // Enhanced error handling with context
+        logger.error(`Failed to ${actionName}`, { actionName, error });
+        throw error;
+      } finally {
+        setIsLoading(false);
+      }
+    };
+  };
+
+  // Fallback functions for when media controls are not available
+  const unavailableAction = async (): Promise<void> => {
+    const errorMsg = !isConnected
+      ? "Cannot control media - not connected to LiveKit room"
+      : "Media controls not available - LiveKit service not initialized";
+    throw new Error(errorMsg);
+  };
+
+  // Simple device switching functions without complex error handling
+  const switchCamera = async (deviceId: string): Promise<void> => {
+    try {
+      if (sdk.livekit?.devices) {
+        await sdk.livekit.devices.switchCamera(deviceId);
+      }
+    } catch (error) {
+      logger.error("Failed to switch camera", { error, deviceId });
+      throw error;
+    }
+  };
+
+  const switchMicrophone = async (deviceId: string): Promise<void> => {
+    try {
+      if (sdk.livekit?.devices) {
+        await sdk.livekit.devices.switchMicrophone(deviceId);
+      }
+    } catch (error) {
+      logger.error("Failed to switch microphone", { error, deviceId });
+      throw error;
+    }
+  };
+
+  const actions: EnhancedMediaActions = mediaControls
+    ? {
+        enableCamera: createEnhancedAction(
+          () => mediaControls?.enableCamera(),
+          "enable camera"
+        ),
+        disableCamera: createEnhancedAction(
+          () => mediaControls?.disableCamera(),
+          "disable camera"
+        ),
+        enableMicrophone: createEnhancedAction(
+          () => mediaControls?.enableMicrophone(),
+          "enable microphone"
+        ),
+        disableMicrophone: createEnhancedAction(
+          () => mediaControls?.disableMicrophone(),
+          "disable microphone"
+        ),
+        toggleCamera: createEnhancedAction(
+          () => mediaControls?.toggleCamera(),
+          "toggle camera"
+        ),
+        toggleMicrophone: createEnhancedAction(
+          () => mediaControls?.toggleMicrophone(),
+          "toggle microphone"
+        ),
+        // Device switching
+        switchCamera,
+        switchMicrophone,
+        // Simple aliases
+        toggleAudio: createEnhancedAction(
+          () => mediaControls?.toggleMicrophone(),
+          "toggle audio"
+        ),
+        toggleVideo: createEnhancedAction(
+          () => mediaControls?.toggleCamera(),
+          "toggle video"
+        ),
+      }
+    : {
+        enableCamera: unavailableAction,
+        disableCamera: unavailableAction,
+        enableMicrophone: unavailableAction,
+        disableMicrophone: unavailableAction,
+        toggleCamera: unavailableAction,
+        toggleMicrophone: unavailableAction,
+        switchCamera: unavailableAction,
+        switchMicrophone: unavailableAction,
+        toggleAudio: unavailableAction,
+        toggleVideo: unavailableAction,
+      };
+
+  return {
+    // State
+    isVideoEnabled: local.videoEnabled,
+    isAudioEnabled: local.audioEnabled,
+    isCameraAvailable: !!mediaControls,
+    isMicrophoneAvailable: !!mediaControls,
+    isConnected,
+    isLoading,
+    errors,
+
+    // Device access
+    devices: {
+      cameras: devices.cams,
+      microphones: devices.mics,
+      speakers: devices.speakers,
+    },
+
+    // Enhanced Actions
+    enableCamera: actions.enableCamera,
+    disableCamera: actions.disableCamera,
+    enableMicrophone: actions.enableMicrophone,
+    disableMicrophone: actions.disableMicrophone,
+    toggleCamera: actions.toggleCamera,
+    toggleMicrophone: actions.toggleMicrophone,
+    // Device switching
+    switchCamera: actions.switchCamera,
+    switchMicrophone: actions.switchMicrophone,
+    // Simple aliases
+    toggleAudio: actions.toggleAudio,
+    toggleVideo: actions.toggleVideo,
+  };
+}

package/packages/sdk/src/hooks/useParticipantStatus.ts

@@ -0,0 +1,318 @@
+import { useEffect, useState } from "react";
+import { SdkEventType, eventBus } from "../core/events";
+import { useRtcStore } from "../state/store";
+import type { Participant } from "../state/types";
+
+/**
+ * Enhanced participant status interface following spec requirements
+ */
+export interface ParticipantStatus {
+  connectionState: "connecting" | "connected" | "reconnecting" | "disconnected";
+  mediaState: {
+    audio: "enabled" | "disabled" | "muted";
+    video: "enabled" | "disabled" | "camera_off";
+  };
+  networkQuality: "excellent" | "good" | "poor" | "lost" | "unknown";
+  lastSeen?: number;
+  speaking?: boolean;
+}
+
+/**
+ * Hook for tracking real-time participant status
+ */
+export function useParticipantStatus(participantId: string): ParticipantStatus {
+  const participant = useRtcStore(
+    (state) => state.room.participants[participantId]
+  );
+  const connection = useRtcStore((state) => state.connection);
+
+  const [status, setStatus] = useState<ParticipantStatus>(() =>
+    getInitialStatus(participant || null, connection.connected)
+  );
+
+  // Update status when participant data changes
+  useEffect(() => {
+    if (!participant) {
+      setStatus(getDisconnectedStatus());
+      return;
+    }
+
+    setStatus((prevStatus) => ({
+      ...prevStatus,
+      connectionState: getConnectionState(participant, connection.connected),
+      mediaState: {
+        audio: getAudioState(participant),
+        video: getVideoState(participant),
+      },
+      networkQuality: participant.connectionQuality || "unknown",
+      lastSeen: participant.joinedAt || Date.now(),
+      speaking: participant.isSpeaking || false,
+    }));
+  }, [participant, connection.connected]);
+
+  // Listen for real-time media events
+  useEffect(() => {
+    const mediaEnabledSub = eventBus.on(SdkEventType.MEDIA_ENABLED, (event) => {
+      if (event.payload.participantId === participantId) {
+        setStatus((prevStatus) => ({
+          ...prevStatus,
+          mediaState: {
+            ...prevStatus.mediaState,
+            [event.payload.mediaType]: "enabled",
+          },
+        }));
+      }
+    });
+
+    const mediaDisabledSub = eventBus.on(
+      SdkEventType.MEDIA_DISABLED,
+      (event) => {
+        if (event.payload.participantId === participantId) {
+          setStatus((prevStatus) => ({
+            ...prevStatus,
+            mediaState: {
+              ...prevStatus.mediaState,
+              [event.payload.mediaType]: "disabled",
+            },
+          }));
+        }
+      }
+    );
+
+    const connectionQualitySub = eventBus.on(
+      SdkEventType.CONNECTION_QUALITY_CHANGED,
+      (event) => {
+        if (event.payload.participantId === participantId) {
+          setStatus((prevStatus) => ({
+            ...prevStatus,
+            networkQuality: event.payload.quality,
+          }));
+        }
+      }
+    );
+
+    const participantJoinedSub = eventBus.on(
+      SdkEventType.PARTICIPANT_JOINED,
+      (event) => {
+        if (event.payload.participant.id === participantId) {
+          setStatus((prevStatus) => ({
+            ...prevStatus,
+            connectionState: "connected",
+            lastSeen: event.timestamp,
+          }));
+        }
+      }
+    );
+
+    const participantLeftSub = eventBus.on(
+      SdkEventType.PARTICIPANT_LEFT,
+      (event) => {
+        if (event.payload.participantId === participantId) {
+          setStatus((prevStatus) => ({
+            ...prevStatus,
+            connectionState: "disconnected",
+            lastSeen: event.timestamp,
+          }));
+        }
+      }
+    );
+
+    return () => {
+      mediaEnabledSub.unsubscribe();
+      mediaDisabledSub.unsubscribe();
+      connectionQualitySub.unsubscribe();
+      participantJoinedSub.unsubscribe();
+      participantLeftSub.unsubscribe();
+    };
+  }, [participantId]);
+
+  return status;
+}
+
+/**
+ * Hook for tracking multiple participants' status
+ */
+export function useParticipantsStatus(
+  participantIds: string[]
+): Record<string, ParticipantStatus> {
+  const [statuses, setStatuses] = useState<Record<string, ParticipantStatus>>(
+    {}
+  );
+
+  useEffect(() => {
+    const updateStatus = (id: string, status: ParticipantStatus) => {
+      setStatuses((prev) => ({
+        ...prev,
+        [id]: status,
+      }));
+    };
+
+    // Initialize statuses
+    const initialStatuses: Record<string, ParticipantStatus> = {};
+    for (const id of participantIds) {
+      initialStatuses[id] = getInitialStatus(null, false);
+    }
+    setStatuses(initialStatuses);
+
+    // Set up event listeners for all participants
+    const subscriptions = [
+      eventBus.onPattern("*", (event) => {
+        const participantId =
+          event.payload?.participantId || event.payload?.participant?.id;
+        if (participantId && participantIds.includes(participantId)) {
+          // Update the specific participant's status
+          setStatuses((prev) => {
+            const currentStatus =
+              prev[participantId] || getInitialStatus(null, false);
+            return {
+              ...prev,
+              [participantId]: updateStatusFromEvent(currentStatus, event),
+            };
+          });
+        }
+      }),
+    ];
+
+    return () => {
+      for (const sub of subscriptions) {
+        sub.unsubscribe();
+      }
+    };
+  }, [participantIds]);
+
+  return statuses;
+}
+
+/**
+ * Hook for getting all participants with their real-time status
+ */
+export function useParticipantsWithStatus(): (Participant & {
+  status: ParticipantStatus;
+})[] {
+  const participants = useRtcStore((state) =>
+    Object.values(state.room.participants)
+  );
+  const connection = useRtcStore((state) => state.connection);
+
+  return participants.map((participant) => ({
+    ...participant,
+    status: {
+      connectionState: getConnectionState(participant, connection.connected),
+      mediaState: {
+        audio: getAudioState(participant),
+        video: getVideoState(participant),
+      },
+      networkQuality: participant.connectionQuality || "unknown",
+      lastSeen: participant.joinedAt || Date.now(),
+      speaking: participant.isSpeaking || false,
+    },
+  }));
+}
+
+function getInitialStatus(
+  participant: Participant | null,
+  isConnected: boolean
+): ParticipantStatus {
+  if (!participant) {
+    return getDisconnectedStatus();
+  }
+
+  return {
+    connectionState: getConnectionState(participant, isConnected),
+    mediaState: {
+      audio: getAudioState(participant),
+      video: getVideoState(participant),
+    },
+    networkQuality: participant.connectionQuality || "unknown",
+    lastSeen: participant.joinedAt || Date.now(),
+    speaking: participant.isSpeaking || false,
+  };
+}
+
+function getDisconnectedStatus(): ParticipantStatus {
+  return {
+    connectionState: "disconnected",
+    mediaState: {
+      audio: "disabled",
+      video: "disabled",
+    },
+    networkQuality: "unknown",
+    speaking: false,
+  };
+}
+
+function getConnectionState(
+  participant: Participant,
+  isGloballyConnected: boolean
+): ParticipantStatus["connectionState"] {
+  if (!isGloballyConnected) {
+    return "disconnected";
+  }
+
+  switch (participant.callState) {
+    case "JOINED":
+      return "connected";
+    case "RINGING":
+    case "INVITED":
+      return "connecting";
+    case "LEFT":
+      return "disconnected";
+    default:
+      return "disconnected";
+  }
+}
+
+function getAudioState(
+  participant: Participant
+): ParticipantStatus["mediaState"]["audio"] {
+  if (!participant.audioEnabled) {
+    return "disabled";
+  }
+  // Could add muted state detection here based on additional data
+  return "enabled";
+}
+
+function getVideoState(
+  participant: Participant
+): ParticipantStatus["mediaState"]["video"] {
+  if (!participant.videoEnabled) {
+    return "camera_off";
+  }
+  return "enabled";
+}
+
+function updateStatusFromEvent(
+  currentStatus: ParticipantStatus,
+  event: any
+): ParticipantStatus {
+  const newStatus = { ...currentStatus };
+
+  switch (event.type) {
+    case SdkEventType.MEDIA_ENABLED:
+      newStatus.mediaState = {
+        ...newStatus.mediaState,
+        [event.payload.mediaType]: "enabled",
+      };
+      break;
+    case SdkEventType.MEDIA_DISABLED:
+      newStatus.mediaState = {
+        ...newStatus.mediaState,
+        [event.payload.mediaType]:
+          event.payload.mediaType === "video" ? "camera_off" : "disabled",
+      };
+      break;
+    case SdkEventType.CONNECTION_QUALITY_CHANGED:
+      newStatus.networkQuality = event.payload.quality;
+      break;
+    case SdkEventType.PARTICIPANT_JOINED:
+      newStatus.connectionState = "connected";
+      newStatus.lastSeen = event.timestamp;
+      break;
+    case SdkEventType.PARTICIPANT_LEFT:
+      newStatus.connectionState = "disconnected";
+      newStatus.lastSeen = event.timestamp;
+      break;
+  }
+
+  return newStatus;
+}