@poolse/react 2.1.6 → 2.2.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 } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall } 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';
 
@@ -485,4 +485,102 @@ declare function sameDay(a: string, b: string): boolean;
  */
 declare function formatDayLabel(iso: string, now?: Date): string;
 
-export { type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseUserState, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser };
+interface UseVoiceRoom {
+    status: VoiceStatus;
+    /** Everyone currently in the room, oldest join first. */
+    participants: VoiceParticipant[];
+    muted: boolean;
+    error: Error | null;
+    /** Acquire the mic and connect. Safe to call twice. */
+    join: () => Promise<void>;
+    leave: () => void;
+    toggleMute: () => void;
+}
+/**
+ * Discord-style voice room for a conversation: join, see who else is
+ * in, watch who's talking, mute yourself.
+ *
+ * The room is torn down when the conversation changes or the component
+ * unmounts, so a navigation away hangs up rather than leaving a phantom
+ * participant behind.
+ *
+ *     const voice = useVoiceRoom(conversationId);
+ *     <Button onPress={voice.join} title="Join Voice" />
+ *
+ * For ringing someone who hasn't joined yet, see `useCalls`.
+ */
+declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions): UseVoiceRoom;
+
+/** Where a call is in its lifecycle, from this device's point of view. */
+type CallPhase = 'idle'
+/** We placed a call and are waiting for an answer. */
+ | 'ringing-out'
+/** Someone is ringing us. */
+ | 'ringing-in'
+/** Both sides agreed; the voice room should be joined now. */
+ | 'active'
+/** The far side said no. */
+ | 'declined'
+/** The person we called is already on another call. */
+ | 'busy'
+/** Nobody picked up before the ring timeout elapsed. */
+ | 'timed-out';
+interface UseCallsOptions {
+    /**
+     * How long a ring may go unanswered, in milliseconds, before it is
+     * given up on. Defaults to 45s, roughly what the mainstream call apps
+     * use. Pass `0` to ring indefinitely.
+     *
+     * The server deliberately holds no timer — only the UI knows when it
+     * stopped waiting — so this is what actually ends an unanswered call.
+     * Both directions are covered: an outbound ring cancels itself, and an
+     * inbound one gives up too, otherwise a caller that crashed mid-ring
+     * would leave the callee's phone ringing forever.
+     */
+    ringTimeoutMs?: number;
+}
+interface UseCalls {
+    phase: CallPhase;
+    /** Set while `phase` is `ringing-in`. */
+    incoming: IncomingCall | null;
+    /** Set while `phase` is `ringing-out` or `active`. */
+    outgoing: OutgoingCall | null;
+    /**
+     * Conversation whose voice room should be joined once `phase` turns
+     * `active` — the same id for both caller and callee.
+     */
+    activeConversationId: string | null;
+    error: Error | null;
+    /** Ring every other member of a conversation. */
+    call: (conversationId: string) => Promise<void>;
+    /** Answer the inbound ring. */
+    accept: () => Promise<void>;
+    /** Reject the inbound ring. */
+    decline: () => Promise<void>;
+    /** Hang up an outbound ring before it's answered. */
+    cancel: () => Promise<void>;
+    /** Drop back to idle — call after leaving the room, or to clear a
+     *  `declined` / `busy` / `timed-out` state the UI has finished
+     *  showing. */
+    reset: () => void;
+}
+/**
+ * WhatsApp-style calling: ring a conversation, show an incoming-call
+ * screen, accept or decline.
+ *
+ * This hook is only the *invitation* half. Audio starts when you join
+ * the voice room, which the host app does once `phase` is `active`:
+ *
+ *     const calls = useCalls(myUserId);
+ *     const voice = useVoiceRoom(calls.activeConversationId);
+ *
+ *     useEffect(() => {
+ *       if (calls.phase === 'active') void voice.join();
+ *     }, [calls.phase]);
+ *
+ * Keeping them separate means a "join voice" button and a ringing call
+ * share exactly one implementation of the media path.
+ */
+declare function useCalls(userId: string | null, opts?: UseCallsOptions): UseCalls;
+
+export { type CallPhase, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCalls, type UseUserState, type UseVoiceRoom, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCalls, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser, useVoiceRoom };

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 } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall } 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';
 
@@ -485,4 +485,102 @@ declare function sameDay(a: string, b: string): boolean;
  */
 declare function formatDayLabel(iso: string, now?: Date): string;
 
-export { type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseUserState, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser };
+interface UseVoiceRoom {
+    status: VoiceStatus;
+    /** Everyone currently in the room, oldest join first. */
+    participants: VoiceParticipant[];
+    muted: boolean;
+    error: Error | null;
+    /** Acquire the mic and connect. Safe to call twice. */
+    join: () => Promise<void>;
+    leave: () => void;
+    toggleMute: () => void;
+}
+/**
+ * Discord-style voice room for a conversation: join, see who else is
+ * in, watch who's talking, mute yourself.
+ *
+ * The room is torn down when the conversation changes or the component
+ * unmounts, so a navigation away hangs up rather than leaving a phantom
+ * participant behind.
+ *
+ *     const voice = useVoiceRoom(conversationId);
+ *     <Button onPress={voice.join} title="Join Voice" />
+ *
+ * For ringing someone who hasn't joined yet, see `useCalls`.
+ */
+declare function useVoiceRoom(conversationId: string | null, opts?: VoiceRoomOptions): UseVoiceRoom;
+
+/** Where a call is in its lifecycle, from this device's point of view. */
+type CallPhase = 'idle'
+/** We placed a call and are waiting for an answer. */
+ | 'ringing-out'
+/** Someone is ringing us. */
+ | 'ringing-in'
+/** Both sides agreed; the voice room should be joined now. */
+ | 'active'
+/** The far side said no. */
+ | 'declined'
+/** The person we called is already on another call. */
+ | 'busy'
+/** Nobody picked up before the ring timeout elapsed. */
+ | 'timed-out';
+interface UseCallsOptions {
+    /**
+     * How long a ring may go unanswered, in milliseconds, before it is
+     * given up on. Defaults to 45s, roughly what the mainstream call apps
+     * use. Pass `0` to ring indefinitely.
+     *
+     * The server deliberately holds no timer — only the UI knows when it
+     * stopped waiting — so this is what actually ends an unanswered call.
+     * Both directions are covered: an outbound ring cancels itself, and an
+     * inbound one gives up too, otherwise a caller that crashed mid-ring
+     * would leave the callee's phone ringing forever.
+     */
+    ringTimeoutMs?: number;
+}
+interface UseCalls {
+    phase: CallPhase;
+    /** Set while `phase` is `ringing-in`. */
+    incoming: IncomingCall | null;
+    /** Set while `phase` is `ringing-out` or `active`. */
+    outgoing: OutgoingCall | null;
+    /**
+     * Conversation whose voice room should be joined once `phase` turns
+     * `active` — the same id for both caller and callee.
+     */
+    activeConversationId: string | null;
+    error: Error | null;
+    /** Ring every other member of a conversation. */
+    call: (conversationId: string) => Promise<void>;
+    /** Answer the inbound ring. */
+    accept: () => Promise<void>;
+    /** Reject the inbound ring. */
+    decline: () => Promise<void>;
+    /** Hang up an outbound ring before it's answered. */
+    cancel: () => Promise<void>;
+    /** Drop back to idle — call after leaving the room, or to clear a
+     *  `declined` / `busy` / `timed-out` state the UI has finished
+     *  showing. */
+    reset: () => void;
+}
+/**
+ * WhatsApp-style calling: ring a conversation, show an incoming-call
+ * screen, accept or decline.
+ *
+ * This hook is only the *invitation* half. Audio starts when you join
+ * the voice room, which the host app does once `phase` is `active`:
+ *
+ *     const calls = useCalls(myUserId);
+ *     const voice = useVoiceRoom(calls.activeConversationId);
+ *
+ *     useEffect(() => {
+ *       if (calls.phase === 'active') void voice.join();
+ *     }, [calls.phase]);
+ *
+ * Keeping them separate means a "join voice" button and a ringing call
+ * share exactly one implementation of the media path.
+ */
+declare function useCalls(userId: string | null, opts?: UseCallsOptions): UseCalls;
+
+export { type CallPhase, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCalls, type UseUserState, type UseVoiceRoom, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCalls, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser, useVoiceRoom };

package/dist/index.js

@@ -1062,7 +1062,186 @@ function formatDayLabel(iso, now = /* @__PURE__ */ new Date()) {
   }
   return d.toLocaleDateString(void 0, { day: "numeric", month: "short", year: "numeric" });
 }
+function useVoiceRoom(conversationId, opts = {}) {
+  const poolse = usePoolse();
+  const [status, setStatus] = useState("idle");
+  const [participants, setParticipants] = useState([]);
+  const [muted, setMuted] = useState(false);
+  const [error, setError] = useState(null);
+  const optsRef = useRef(opts);
+  const room = useMemo(
+    () => conversationId ? poolse.realtime.voice(conversationId, optsRef.current) : null,
+    [poolse, conversationId]
+  );
+  useEffect(() => {
+    if (!room) return;
+    setStatus(room.getStatus());
+    setParticipants(room.getParticipants());
+    setMuted(room.isMuted());
+    const offStatus = room.onStatus(setStatus);
+    const offRoster = room.onParticipants(setParticipants);
+    const offError = room.onError(setError);
+    return () => {
+      offStatus();
+      offRoster();
+      offError();
+      room.leave();
+    };
+  }, [room]);
+  const join = useCallback(async () => {
+    if (!room) return;
+    setError(null);
+    try {
+      await room.join();
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }, [room]);
+  const leave = useCallback(() => {
+    room?.leave();
+  }, [room]);
+  const toggleMute = useCallback(() => {
+    if (!room) return;
+    setMuted(room.toggleMute());
+  }, [room]);
+  return { status, participants, muted, error, join, leave, toggleMute };
+}
+function useCalls(userId, opts = {}) {
+  const ringTimeoutMs = opts.ringTimeoutMs ?? 45e3;
+  const poolse = usePoolse();
+  const [phase, setPhase] = useState("idle");
+  const [incoming, setIncoming] = useState(null);
+  const [outgoing, setOutgoing] = useState(null);
+  const [activeConversationId, setActiveConversationId] = useState(null);
+  const [error, setError] = useState(null);
+  const actionsRef = useRef({
+    cancel: async () => {
+    },
+    decline: async () => {
+    }
+  });
+  const calls = useMemo(() => userId ? poolse.realtime.calls(userId) : null, [poolse, userId]);
+  useEffect(() => {
+    if (!calls) return;
+    const offIncoming = calls.onIncoming((call2) => {
+      setPhase((current) => {
+        if (current !== "idle") {
+          void calls.markBusy(call2).catch(() => {
+          });
+          return current;
+        }
+        setIncoming(call2);
+        return "ringing-in";
+      });
+    });
+    const offAccepted = calls.onAccepted((call2) => {
+      setPhase("active");
+      setActiveConversationId(call2.conversationId);
+    });
+    const offDeclined = calls.onDeclined(() => {
+      setPhase("declined");
+      setOutgoing(null);
+    });
+    const offBusy = calls.onBusy(() => {
+      setPhase("busy");
+      setOutgoing(null);
+    });
+    const offCancelled = calls.onCancelled((call2) => {
+      setIncoming((current) => {
+        if (current && current.callId !== call2.callId) return current;
+        setPhase("idle");
+        return null;
+      });
+    });
+    return () => {
+      offIncoming();
+      offAccepted();
+      offDeclined();
+      offBusy();
+      offCancelled();
+    };
+  }, [calls]);
+  const call = useCallback(
+    async (conversationId) => {
+      if (!calls) return;
+      setError(null);
+      try {
+        const placed = await calls.invite(conversationId);
+        setOutgoing(placed);
+        setPhase("ringing-out");
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setPhase("idle");
+      }
+    },
+    [calls]
+  );
+  const accept = useCallback(async () => {
+    if (!calls || !incoming) return;
+    try {
+      await calls.accept(incoming);
+      setActiveConversationId(incoming.conversationId);
+      setPhase("active");
+      setIncoming(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }, [calls, incoming]);
+  const decline = useCallback(async () => {
+    if (!calls || !incoming) return;
+    try {
+      await calls.decline(incoming);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIncoming(null);
+      setPhase("idle");
+    }
+  }, [calls, incoming]);
+  const cancel = useCallback(async () => {
+    if (!calls || !outgoing) return;
+    try {
+      await calls.cancel(outgoing);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setOutgoing(null);
+      setPhase("idle");
+    }
+  }, [calls, outgoing]);
+  actionsRef.current = { cancel, decline };
+  useEffect(() => {
+    if (ringTimeoutMs <= 0) return;
+    if (phase !== "ringing-out" && phase !== "ringing-in") return;
+    const outbound = phase === "ringing-out";
+    const timer = setTimeout(() => {
+      void (outbound ? actionsRef.current.cancel() : actionsRef.current.decline()).finally(() => {
+        if (outbound) setPhase("timed-out");
+      });
+    }, ringTimeoutMs);
+    return () => clearTimeout(timer);
+  }, [phase, ringTimeoutMs]);
+  const reset = useCallback(() => {
+    setPhase("idle");
+    setIncoming(null);
+    setOutgoing(null);
+    setActiveConversationId(null);
+    setError(null);
+  }, []);
+  return {
+    phase,
+    incoming,
+    outgoing,
+    activeConversationId,
+    error,
+    call,
+    accept,
+    decline,
+    cancel,
+    reset
+  };
+}
 
-export { PoolseProvider, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser };
+export { PoolseProvider, computeGroupPosition, formatDayLabel, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCalls, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping, useUser, useVoiceRoom };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map