@poolse/react 2.12.1 → 2.13.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, CameraFacing, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia } from '@poolse/sdk';
 export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, Conversation, ConversationCreateRequest, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, RealtimeStatus, Uuid } from '@poolse/sdk';
 import { ReactNode } from 'react';
 
@@ -501,6 +501,14 @@ interface UseCallRoomOptions {
     video?: boolean;
     /** Join muted. */
     muted?: boolean;
+    /** Which camera to open with. Defaults to the front one. */
+    facing?: CameraFacing;
+    /**
+     * How long the last participant may sit alone before {@link
+     * UseCallRoom.alone} turns true, in milliseconds. Defaults to 1500.
+     * Pass `0` to never report it.
+     */
+    aloneGraceMs?: number;
 }
 interface UseCallRoom {
     status: CallRoomStatus;
@@ -508,6 +516,22 @@ interface UseCallRoom {
     participants: CallParticipant[];
     cameraEnabled: boolean;
     micEnabled: boolean;
+    /** Which camera is publishing. Meaningless while the camera is off. */
+    facingMode: CameraFacing;
+    /**
+     * Everyone else has gone and is not coming back.
+     *
+     * Turns true only after somebody else has actually been on the call,
+     * so the caller waiting for an answer never trips it. Wire it to your
+     * hang-up path — a peer whose app was killed or whose phone lost
+     * signal sends no `call:hangup`, and without this the survivor is
+     * left on a call screen that will never close on its own.
+     *
+     *     useEffect(() => {
+     *       if (media.alone) void calls.hangUp();
+     *     }, [media.alone]);
+     */
+    alone: boolean;
     error: Error | null;
     /**
      * Whether this deployment has an SFU.
@@ -522,6 +546,8 @@ interface UseCallRoom {
     leave: () => void;
     setCameraEnabled: (enabled: boolean) => Promise<void>;
     toggleCamera: () => Promise<void>;
+    /** Swap between the front and rear cameras. */
+    switchCamera: () => Promise<void>;
     setMicrophoneEnabled: (enabled: boolean) => Promise<void>;
     toggleMic: () => Promise<void>;
 }
@@ -547,6 +573,16 @@ interface UseVoiceRoom {
     /** Everyone currently in the room, oldest join first. */
     participants: VoiceParticipant[];
     muted: boolean;
+    /**
+     * Everyone else has left and is not coming back.
+     *
+     * The mesh equivalent of `useCallRoom`'s flag of the same name — see
+     * there for why a call needs this on top of the explicit hang-up
+     * signal. Only meaningful for a room being used to carry a call; a
+     * Discord-style room you sit in alone is a normal state, so wire this
+     * to hang-up only on the call surface.
+     */
+    alone: boolean;
     error: Error | null;
     /** Acquire the mic and connect. Safe to call twice. */
     join: () => Promise<void>;
@@ -566,7 +602,10 @@ interface UseVoiceRoom {
  *
  * For ringing someone who hasn't joined yet, see `useCalls`.
  */
-declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions): UseVoiceRoom;
+declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions & {
+    /** Grace before {@link UseVoiceRoom.alone}. Defaults to 1500; `0` disables. */
+    aloneGraceMs?: number;
+}): UseVoiceRoom;
 
 /** Where a call is in its lifecycle, from this device's point of view. */
 type CallPhase = 'idle'

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, CameraFacing, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia } from '@poolse/sdk';
 export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, Conversation, ConversationCreateRequest, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, RealtimeStatus, Uuid } from '@poolse/sdk';
 import { ReactNode } from 'react';
 
@@ -501,6 +501,14 @@ interface UseCallRoomOptions {
     video?: boolean;
     /** Join muted. */
     muted?: boolean;
+    /** Which camera to open with. Defaults to the front one. */
+    facing?: CameraFacing;
+    /**
+     * How long the last participant may sit alone before {@link
+     * UseCallRoom.alone} turns true, in milliseconds. Defaults to 1500.
+     * Pass `0` to never report it.
+     */
+    aloneGraceMs?: number;
 }
 interface UseCallRoom {
     status: CallRoomStatus;
@@ -508,6 +516,22 @@ interface UseCallRoom {
     participants: CallParticipant[];
     cameraEnabled: boolean;
     micEnabled: boolean;
+    /** Which camera is publishing. Meaningless while the camera is off. */
+    facingMode: CameraFacing;
+    /**
+     * Everyone else has gone and is not coming back.
+     *
+     * Turns true only after somebody else has actually been on the call,
+     * so the caller waiting for an answer never trips it. Wire it to your
+     * hang-up path — a peer whose app was killed or whose phone lost
+     * signal sends no `call:hangup`, and without this the survivor is
+     * left on a call screen that will never close on its own.
+     *
+     *     useEffect(() => {
+     *       if (media.alone) void calls.hangUp();
+     *     }, [media.alone]);
+     */
+    alone: boolean;
     error: Error | null;
     /**
      * Whether this deployment has an SFU.
@@ -522,6 +546,8 @@ interface UseCallRoom {
     leave: () => void;
     setCameraEnabled: (enabled: boolean) => Promise<void>;
     toggleCamera: () => Promise<void>;
+    /** Swap between the front and rear cameras. */
+    switchCamera: () => Promise<void>;
     setMicrophoneEnabled: (enabled: boolean) => Promise<void>;
     toggleMic: () => Promise<void>;
 }
@@ -547,6 +573,16 @@ interface UseVoiceRoom {
     /** Everyone currently in the room, oldest join first. */
     participants: VoiceParticipant[];
     muted: boolean;
+    /**
+     * Everyone else has left and is not coming back.
+     *
+     * The mesh equivalent of `useCallRoom`'s flag of the same name — see
+     * there for why a call needs this on top of the explicit hang-up
+     * signal. Only meaningful for a room being used to carry a call; a
+     * Discord-style room you sit in alone is a normal state, so wire this
+     * to hang-up only on the call surface.
+     */
+    alone: boolean;
     error: Error | null;
     /** Acquire the mic and connect. Safe to call twice. */
     join: () => Promise<void>;
@@ -566,7 +602,10 @@ interface UseVoiceRoom {
  *
  * For ringing someone who hasn't joined yet, see `useCalls`.
  */
-declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions): UseVoiceRoom;
+declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions & {
+    /** Grace before {@link UseVoiceRoom.alone}. Defaults to 1500; `0` disables. */
+    aloneGraceMs?: number;
+}): UseVoiceRoom;
 
 /** Where a call is in its lifecycle, from this device's point of view. */
 type CallPhase = 'idle'

package/dist/index.js

@@ -1068,22 +1068,28 @@ function useCallRoom(conversationId, opts) {
   const [participants, setParticipants] = useState([]);
   const [cameraEnabled, setCamera] = useState(false);
   const [micEnabled, setMic] = useState(false);
+  const [facingMode, setFacing] = useState(opts.facing ?? "user");
+  const [alone, setAlone] = useState(false);
   const [error, setError] = useState(null);
   const [sfuAvailable, setSfuAvailable] = useState(null);
   const optsRef = useRef(opts);
+  optsRef.current = opts;
   const joined = useRef(false);
   const room = useMemo(() => {
     if (!conversationId) return null;
     return poolse.call(conversationId, {
       livekit: optsRef.current.livekit,
       ...optsRef.current.video !== void 0 ? { video: optsRef.current.video } : {},
-      ...optsRef.current.muted !== void 0 ? { muted: optsRef.current.muted } : {}
+      ...optsRef.current.muted !== void 0 ? { muted: optsRef.current.muted } : {},
+      ...optsRef.current.facing !== void 0 ? { facing: optsRef.current.facing } : {},
+      ...optsRef.current.aloneGraceMs !== void 0 ? { aloneGraceMs: optsRef.current.aloneGraceMs } : {}
     });
   }, [poolse, conversationId]);
   const sync = useCallback((target) => {
     if (!target) return;
     setCamera(target.isCameraEnabled());
     setMic(target.isMicrophoneEnabled());
+    setFacing(target.getFacingMode());
   }, []);
   useEffect(() => {
     if (!room) {
@@ -1093,15 +1099,18 @@ function useCallRoom(conversationId, opts) {
     }
     setStatus(room.getStatus());
     setParticipants(room.getParticipants());
+    setAlone(false);
     const offStatus = room.onStatus(setStatus);
     const offRoster = room.onParticipants((next) => {
       setParticipants(next);
       sync(room);
     });
+    const offAlone = room.onAlone(() => setAlone(true));
     const offError = room.onError(setError);
     return () => {
       offStatus();
       offRoster();
+      offAlone();
       offError();
       if (joined.current) {
         joined.current = false;
@@ -1153,21 +1162,50 @@ function useCallRoom(conversationId, opts) {
     if (!room) return;
     await setMicrophoneEnabled(!room.isMicrophoneEnabled());
   }, [room, setMicrophoneEnabled]);
+  const switchCamera = useCallback(async () => {
+    if (!room) return;
+    await room.switchCamera();
+    setFacing(room.getFacingMode());
+  }, [room]);
   return {
     status,
     participants,
     cameraEnabled,
     micEnabled,
+    facingMode,
+    alone,
     error,
     sfuAvailable,
     join,
     leave,
     setCameraEnabled,
     toggleCamera,
+    switchCamera,
     setMicrophoneEnabled,
     toggleMic
   };
 }
+function useAloneWatch({ active, others, graceMs }) {
+  const [alone, setAlone] = useState(false);
+  const seenPeer = useRef(false);
+  useEffect(() => {
+    if (!active) {
+      seenPeer.current = false;
+      setAlone(false);
+      return;
+    }
+    if (others > 0) {
+      seenPeer.current = true;
+      return;
+    }
+    if (graceMs <= 0 || !seenPeer.current) return;
+    const timer = setTimeout(() => setAlone(true), graceMs);
+    return () => clearTimeout(timer);
+  }, [active, others, graceMs]);
+  return alone;
+}
+
+// src/use-voice-room.ts
 function useVoiceRoom(conversationId, opts = {}) {
   const poolse = usePoolse();
   const [status, setStatus] = useState("idle");
@@ -1217,7 +1255,12 @@ function useVoiceRoom(conversationId, opts = {}) {
     if (!room) return;
     setMuted(room.toggleMute());
   }, [room]);
-  return { status, participants, muted, error, join, leave, toggleMute };
+  const alone = useAloneWatch({
+    active: status === "connected",
+    others: Math.max(0, participants.length - 1),
+    graceMs: optsRef.current.aloneGraceMs ?? 1500
+  });
+  return { status, participants, muted, alone, error, join, leave, toggleMute };
 }
 function useCalls(userId, opts = {}) {
   const ringTimeoutMs = opts.ringTimeoutMs ?? 45e3;