vg-x07df 0.1.0

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

@@ -0,0 +1,296 @@
+import { Room } from "livekit-client";
+import { useCallback, useEffect, useState } from "react";
+import { useSdk } from "../provider/RtcProvider";
+import { useRtcStore } from "../state/store";
+import type { DeviceState, PermissionStatus, RtcError } from "../state/types";
+import { createLogger } from "../utils/logger";
+
+const logger = createLogger("hooks:devices");
+
+export interface DeviceActions {
+  switchCamera: (deviceId: string) => Promise<void>;
+  switchMicrophone: (deviceId: string) => Promise<void>;
+  switchSpeaker: (deviceId: string) => Promise<void>;
+  listDevices: () => Promise<void>;
+  refreshDevices: () => Promise<void>;
+  requestPermissions: (kind: "microphone" | "camera" | "both") => Promise<void>;
+  checkPermissions: () => Promise<void>;
+}
+
+export interface DevicesHook extends DeviceState, DeviceActions {
+  isConnected: boolean;
+  errors: RtcError[];
+}
+
+export function useDevices(): DevicesHook {
+  const sdk = useSdk();
+  const devices = useRtcStore((state) => state.devices);
+  const connection = useRtcStore((state) => state.connection);
+  const errors = useRtcStore((state) =>
+    state.errors.filter((e) => e.code.startsWith("DEVICE_"))
+  );
+
+  const [localLoading, setLocalLoading] = useState(false);
+
+  const isConnected = connection.connected;
+  let deviceManager = null;
+
+  try {
+    if (sdk.livekit && isConnected) {
+      deviceManager = sdk.livekit.devices;
+    }
+  } catch {
+    deviceManager = null;
+  }
+
+  const createSwitchAction = useCallback(
+    (
+      switchFn: (deviceId: string) => Promise<void> | undefined,
+      actionName: string
+    ) => {
+      return async (deviceId: string): Promise<void> => {
+        if (!deviceManager) {
+          const errorMsg = !isConnected
+            ? "Cannot switch device - not connected to LiveKit room"
+            : "Device manager not available - LiveKit service not initialized";
+          throw new Error(errorMsg);
+        }
+
+        setLocalLoading(true);
+        try {
+          const result = switchFn(deviceId);
+          if (result) {
+            await result;
+          }
+        } catch (error) {
+          logger.error(`Failed to ${actionName}`, { actionName, error });
+          throw error;
+        } finally {
+          setLocalLoading(false);
+        }
+      };
+    },
+    [deviceManager, isConnected]
+  );
+
+  const switchCamera = createSwitchAction(
+    (deviceId: string) => deviceManager?.switchCamera(deviceId),
+    "switch camera"
+  );
+
+  const switchMicrophone = createSwitchAction(
+    (deviceId: string) => deviceManager?.switchMicrophone(deviceId),
+    "switch microphone"
+  );
+
+  const switchSpeaker = createSwitchAction(
+    (deviceId: string) => deviceManager?.switchSpeaker(deviceId),
+    "switch speaker"
+  );
+
+  // Pre-connection device listing using LiveKit static method
+  const listDevices = useCallback(async (): Promise<void> => {
+    setLocalLoading(true);
+    try {
+      const [mics, cams, speakers] = await Promise.all([
+        Room.getLocalDevices("audioinput", false), // Don't request permissions
+        Room.getLocalDevices("videoinput", false),
+        Room.getLocalDevices("audiooutput", false),
+      ]);
+
+      useRtcStore.getState().patch((state) => {
+        state.devices.mics = mics;
+        state.devices.cams = cams;
+        state.devices.speakers = speakers;
+        state.devices.isEnumerating = false;
+        state.devices.lastEnumeratedAt = Date.now();
+      });
+    } catch (error) {
+      logger.error("Failed to list devices", { error });
+      throw error;
+    } finally {
+      setLocalLoading(false);
+    }
+  }, []);
+
+  // Request permissions and refresh device labels
+  const requestPermissions = useCallback(
+    async (kind: "microphone" | "camera" | "both"): Promise<void> => {
+      setLocalLoading(true);
+      try {
+        // Use LiveKit's permission-requesting device enumeration
+        if (kind === "microphone" || kind === "both") {
+          await Room.getLocalDevices("audioinput", true); // Request permissions
+          useRtcStore.getState().patch((state) => {
+            state.devices.permissions.microphone = "granted";
+          });
+        }
+
+        if (kind === "camera" || kind === "both") {
+          await Room.getLocalDevices("videoinput", true); // Request permissions
+          useRtcStore.getState().patch((state) => {
+            state.devices.permissions.camera = "granted";
+          });
+        }
+
+        // Refresh all devices to get updated labels
+        await listDevices();
+      } catch (error) {
+        logger.error("Failed to request permissions", { kind, error });
+
+        // Update permission state based on error type
+        useRtcStore.getState().patch((state) => {
+          if (kind === "microphone" || kind === "both") {
+            state.devices.permissions.microphone = "denied";
+          }
+          if (kind === "camera" || kind === "both") {
+            state.devices.permissions.camera = "denied";
+          }
+        });
+
+        throw error;
+      } finally {
+        setLocalLoading(false);
+      }
+    },
+    [listDevices]
+  );
+
+  const refreshDevices = useCallback(async (): Promise<void> => {
+    if (deviceManager && isConnected) {
+      // Use connected device manager when available
+      setLocalLoading(true);
+      try {
+        await deviceManager.enumerateDevices();
+      } catch (error) {
+        logger.error("Failed to refresh devices", { error });
+        throw error;
+      } finally {
+        setLocalLoading(false);
+      }
+    } else {
+      // Fall back to pre-connection listing
+      await listDevices();
+    }
+  }, [deviceManager, isConnected, listDevices]);
+
+  const checkPermissions = useCallback(async (): Promise<void> => {
+    if (!navigator.permissions) {
+      return;
+    }
+
+    try {
+      const [cameraPermission, microphonePermission] = await Promise.all([
+        navigator.permissions.query({ name: "camera" as PermissionName }),
+        navigator.permissions.query({ name: "microphone" as PermissionName }),
+      ]);
+
+      useRtcStore.getState().patch((state) => {
+        state.devices.permissions.camera =
+          cameraPermission.state as PermissionStatus;
+        state.devices.permissions.microphone =
+          microphonePermission.state as PermissionStatus;
+      });
+
+      cameraPermission.onchange = () => {
+        useRtcStore.getState().patch((state) => {
+          state.devices.permissions.camera =
+            cameraPermission.state as PermissionStatus;
+        });
+      };
+
+      microphonePermission.onchange = () => {
+        useRtcStore.getState().patch((state) => {
+          state.devices.permissions.microphone =
+            microphonePermission.state as PermissionStatus;
+        });
+      };
+    } catch (error) {
+      logger.warn("Failed to check device permissions", { error });
+      useRtcStore.getState().patch((state) => {
+        state.devices.permissions.camera = "unknown";
+        state.devices.permissions.microphone = "unknown";
+      });
+    }
+  }, []);
+
+  useEffect(() => {
+    // Auto-list devices on mount (works pre-connection)
+    listDevices().catch((error) => {
+      logger.warn("Failed to auto-list devices", { error });
+    });
+
+    checkPermissions().catch((error) => {
+      logger.warn("Failed to check permissions", { error });
+    });
+  }, [listDevices, checkPermissions]);
+
+  useEffect(() => {
+    // Re-enumerate when connected to get more accurate device info
+    if (isConnected && deviceManager) {
+      refreshDevices().catch((error) => {
+        logger.warn("Failed to refresh devices after connection", { error });
+      });
+    }
+  }, [isConnected, deviceManager, refreshDevices]);
+
+  const unavailableAction = async (): Promise<void> => {
+    const errorMsg = !isConnected
+      ? "Cannot perform device operation - not connected to LiveKit room"
+      : "Device manager not available - LiveKit service not initialized";
+    throw new Error(errorMsg);
+  };
+
+  const isEnumerating = devices.isEnumerating || localLoading;
+
+  return {
+    mics: devices.mics,
+    cams: devices.cams,
+    speakers: devices.speakers,
+    selected: devices.selected,
+    permissions: devices.permissions,
+    isEnumerating,
+    lastEnumeratedAt: devices.lastEnumeratedAt,
+
+    isConnected,
+    errors,
+
+    switchCamera: deviceManager ? switchCamera : unavailableAction,
+    switchMicrophone: deviceManager ? switchMicrophone : unavailableAction,
+    switchSpeaker: deviceManager ? switchSpeaker : unavailableAction,
+    listDevices, // Always available (works pre-connection)
+    refreshDevices, // Now works both pre and post connection
+    requestPermissions, // Always available (works pre-connection)
+    checkPermissions,
+  };
+}
+
+export function useDeviceState(): DeviceState {
+  return useRtcStore((state) => state.devices);
+}
+
+export function useDevicePermissions(): {
+  camera: PermissionStatus;
+  microphone: PermissionStatus;
+  isPermissionGranted: (type: "camera" | "microphone") => boolean;
+  hasAnyPermission: boolean;
+} {
+  const permissions = useRtcStore((state) => state.devices.permissions);
+
+  const isPermissionGranted = useCallback(
+    (type: "camera" | "microphone"): boolean => {
+      return permissions[type] === "granted";
+    },
+    [permissions]
+  );
+
+  const hasAnyPermission =
+    permissions.camera === "granted" || permissions.microphone === "granted";
+
+  return {
+    camera: permissions.camera,
+    microphone: permissions.microphone,
+    isPermissionGranted,
+    hasAnyPermission,
+  };
+}

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

@@ -0,0 +1,299 @@
+import { useEffect, useState } from "react";
+import { eventBus } from "../core/events";
+import {
+  type ErrorRecoveryConfig,
+  type RetryContext,
+  errorRecoveryService,
+} from "../services/error-recovery";
+import type { RtcError } from "../state/types";
+
+/**
+ * Error recovery status interface
+ */
+export interface ErrorRecoveryStatus {
+  isRecovering: boolean;
+  activeRetries: Map<string, RetryContext>;
+  lastRecoveryAttempt?: {
+    error: RtcError;
+    attempts: number;
+    timestamp: number;
+  };
+  lastRecoveryResult?: {
+    error: RtcError;
+    attempts: number;
+    success: boolean;
+    timestamp: number;
+  };
+}
+
+/**
+ * Hook for monitoring and controlling error recovery
+ *
+ * Provides real-time status of error recovery attempts and allows
+ * configuration of recovery behavior.
+ *
+ * @param config - Optional recovery configuration override
+ * @returns Error recovery status and control methods
+ *
+ * @example
+ * const {
+ *   status,
+ *   updateConfig,
+ *   cancelRetry,
+ *   cancelAllRetries
+ * } = useErrorRecovery();
+ *
+ * // Monitor recovery status
+ * if (status.isRecovering) {
+ *   // Handle recovery state
+ * }
+ *
+ * // Configure recovery behavior
+ * updateConfig({ maxRetries: 5, retryDelay: 2000 });
+ */
+export function useErrorRecovery(config?: Partial<ErrorRecoveryConfig>) {
+  const [status, setStatus] = useState<ErrorRecoveryStatus>({
+    isRecovering: false,
+    activeRetries: new Map(),
+  });
+
+  useEffect(() => {
+    // Apply config if provided
+    if (config) {
+      errorRecoveryService.updateConfig(config);
+    }
+
+    // Listen for recovery events
+    const recoveryAttemptSub = eventBus.on("recovery:attempt", (event) => {
+      setStatus((prev) => ({
+        ...prev,
+        isRecovering: true,
+        lastRecoveryAttempt: event.payload,
+        activeRetries: errorRecoveryService.getActiveRetries(),
+      }));
+    });
+
+    const recoverySuccessSub = eventBus.on("recovery:success", (event) => {
+      setStatus((prev) => ({
+        ...prev,
+        isRecovering: false,
+        lastRecoveryResult: {
+          ...event.payload,
+          success: true,
+        },
+        activeRetries: errorRecoveryService.getActiveRetries(),
+      }));
+    });
+
+    const recoveryFailedSub = eventBus.on("recovery:failed", (event) => {
+      setStatus((prev) => ({
+        ...prev,
+        isRecovering: false,
+        lastRecoveryResult: {
+          ...event.payload,
+          success: false,
+        },
+        activeRetries: errorRecoveryService.getActiveRetries(),
+      }));
+    });
+
+    // Update active retries periodically
+    const updateInterval = setInterval(() => {
+      setStatus((prev) => ({
+        ...prev,
+        activeRetries: errorRecoveryService.getActiveRetries(),
+        isRecovering: errorRecoveryService.getActiveRetries().size > 0,
+      }));
+    }, 1000);
+
+    return () => {
+      recoveryAttemptSub.unsubscribe();
+      recoverySuccessSub.unsubscribe();
+      recoveryFailedSub.unsubscribe();
+      clearInterval(updateInterval);
+    };
+  }, [config]);
+
+  const updateConfig = (newConfig: Partial<ErrorRecoveryConfig>) => {
+    errorRecoveryService.updateConfig(newConfig);
+  };
+
+  const cancelRetry = (retryKey: string) => {
+    const cancelled = errorRecoveryService.cancelRetry(retryKey);
+    if (cancelled) {
+      setStatus((prev) => ({
+        ...prev,
+        activeRetries: errorRecoveryService.getActiveRetries(),
+        isRecovering: errorRecoveryService.getActiveRetries().size > 0,
+      }));
+    }
+    return cancelled;
+  };
+
+  const cancelAllRetries = () => {
+    errorRecoveryService.cancelAllRetries();
+    setStatus((prev) => ({
+      ...prev,
+      activeRetries: new Map(),
+      isRecovering: false,
+    }));
+  };
+
+  return {
+    status,
+    updateConfig,
+    cancelRetry,
+    cancelAllRetries,
+  };
+}
+
+/**
+ * Hook for monitoring recovery of a specific error type
+ *
+ * @param errorCode - The error code to monitor
+ * @returns Recovery status for the specific error type
+ */
+export function useErrorRecoveryForType(errorCode: string) {
+  const [isRecovering, setIsRecovering] = useState(false);
+  const [lastAttempt, setLastAttempt] = useState<number>(0);
+  const [lastResult, setLastResult] = useState<{
+    success: boolean;
+    timestamp: number;
+  } | null>(null);
+
+  useEffect(() => {
+    const recoveryAttemptSub = eventBus.on("recovery:attempt", (event) => {
+      if (event.payload.error.code === errorCode) {
+        setIsRecovering(true);
+        setLastAttempt(event.payload.attempts);
+      }
+    });
+
+    const recoverySuccessSub = eventBus.on("recovery:success", (event) => {
+      if (event.payload.error.code === errorCode) {
+        setIsRecovering(false);
+        setLastResult({ success: true, timestamp: event.payload.timestamp });
+      }
+    });
+
+    const recoveryFailedSub = eventBus.on("recovery:failed", (event) => {
+      if (event.payload.error.code === errorCode) {
+        setIsRecovering(false);
+        setLastResult({ success: false, timestamp: event.payload.timestamp });
+      }
+    });
+
+    return () => {
+      recoveryAttemptSub.unsubscribe();
+      recoverySuccessSub.unsubscribe();
+      recoveryFailedSub.unsubscribe();
+    };
+  }, [errorCode]);
+
+  return {
+    isRecovering,
+    lastAttempt,
+    lastResult,
+  };
+}
+
+/**
+ * Hook for automatic graceful degradation
+ *
+ * Automatically handles graceful degradation scenarios like
+ * falling back to audio-only when video fails.
+ *
+ * @param degradationConfig - Configuration for degradation behavior
+ */
+export function useGracefulDegradation(degradationConfig?: {
+  enableAudioOnlyFallback?: boolean;
+  enableLowerQualityFallback?: boolean;
+  notifyUser?: boolean;
+}) {
+  const config = {
+    enableAudioOnlyFallback: true,
+    enableLowerQualityFallback: true,
+    notifyUser: true,
+    ...degradationConfig,
+  };
+
+  const [degradationStatus, setDegradationStatus] = useState({
+    isAudioOnly: false,
+    isLowerQuality: false,
+    reason: null as string | null,
+  });
+
+  useEffect(() => {
+    // Listen for media failures that might trigger degradation
+    const mediaDisabledSub = eventBus.on("media:disabled", (event) => {
+      if (
+        event.payload.mediaType === "video" &&
+        config.enableAudioOnlyFallback
+      ) {
+        setDegradationStatus((prev) => ({
+          ...prev,
+          isAudioOnly: true,
+          reason: "video_disabled",
+        }));
+
+        if (config.notifyUser) {
+          // Could emit a user notification event here
+          eventBus.emit(
+            "degradation:audio-only",
+            {
+              reason: "video_disabled",
+              timestamp: Date.now(),
+            },
+            "user"
+          );
+        }
+      }
+    });
+
+    // Listen for connection quality changes that might trigger degradation
+    const qualityChangedSub = eventBus.on(
+      "connection:quality-changed",
+      (event) => {
+        if (
+          event.payload.quality === "poor" &&
+          config.enableLowerQualityFallback
+        ) {
+          setDegradationStatus((prev) => ({
+            ...prev,
+            isLowerQuality: true,
+            reason: "poor_connection",
+          }));
+
+          if (config.notifyUser) {
+            eventBus.emit(
+              "degradation:lower-quality",
+              {
+                reason: "poor_connection",
+                timestamp: Date.now(),
+              },
+              "user"
+            );
+          }
+        }
+      }
+    );
+
+    return () => {
+      mediaDisabledSub.unsubscribe();
+      qualityChangedSub.unsubscribe();
+    };
+  }, [config]);
+
+  const resetDegradation = () => {
+    setDegradationStatus({
+      isAudioOnly: false,
+      isLowerQuality: false,
+      reason: null,
+    });
+  };
+
+  return {
+    degradationStatus,
+    resetDegradation,
+  };
+}

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

@@ -0,0 +1,84 @@
+import { useCallback } from "react";
+import { clearErrors } from "../state/errors";
+import type { ErrorCode, RtcError } from "../state/errors";
+import { useRtcStore } from "../state/store";
+
+export interface UseErrorsReturn {
+  errors: RtcError[];
+  clearAll: () => void;
+  clearByCode: (code: ErrorCode) => void;
+  clearByPredicate: (predicate: (error: RtcError) => boolean) => void;
+  hasErrors: boolean;
+  errorCount: number;
+  latestError: RtcError | undefined;
+}
+
+/**
+ * Hook for apps to consume and manage SDK errors
+ *
+ * Provides read access to all errors and methods to clear them.
+ * Perfect for implementing toast notifications, error logging, and telemetry.
+ *
+ * @example
+ * const { errors, clearAll, hasErrors } = useErrors();
+ *
+ * // Show toast for new errors
+ * useEffect(() => {
+ *   if (hasErrors) {
+ *     showToast(errors[errors.length - 1].message);
+ *   }
+ * }, [errors, hasErrors]);
+ */
+export function useErrors(): UseErrorsReturn {
+  // Subscribe to errors array in store
+  const errors = useRtcStore((state) => state.errors);
+
+  // Clear all errors
+  const clearAll = useCallback(() => {
+    clearErrors();
+  }, []);
+
+  // Clear errors by code
+  const clearByCode = useCallback((code: ErrorCode) => {
+    clearErrors((error) => error.code === code);
+  }, []);
+
+  // Clear errors by custom predicate
+  const clearByPredicate = useCallback(
+    (predicate: (error: RtcError) => boolean) => {
+      clearErrors(predicate);
+    },
+    []
+  );
+
+  return {
+    errors,
+    clearAll,
+    clearByCode,
+    clearByPredicate,
+    hasErrors: errors.length > 0,
+    errorCount: errors.length,
+    latestError: errors[errors.length - 1] || undefined,
+  };
+}
+
+/**
+ * Hook to get errors of specific types
+ * Useful for filtering errors by category
+ *
+ * @example
+ * const deviceErrors = useErrorsByCode(['DEVICE_SWITCH', 'MEDIA_PERMISSION']);
+ */
+export function useErrorsByCode(codes: ErrorCode[]): RtcError[] {
+  return useRtcStore((state) =>
+    state.errors.filter((error) => codes.includes(error.code as ErrorCode))
+  );
+}
+
+/**
+ * Hook to get the count of errors by code
+ * Useful for badges and indicators
+ */
+export function useErrorCount(): number {
+  return useRtcStore((state) => state.errors.length);
+}