@poolse/react 2.27.0 → 2.29.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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, CameraFacing, CallDeviceKind, CallDevice, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia, LiveCall } from '@poolse/sdk';
-export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, CallEndReason, CallLog, CallLogDisplay, CallLogEntry, CallLogMedia, CallMissedEntry, CallParticipantStatus, Conversation, ConversationCreateRequest, DeviceKind, LiveCall, LiveCallMember, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, ReadReceiptsState, RealtimeStatus, Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, CameraFacing, CallDeviceKind, CallDevice, LiveKitModule, LiveCall } from '@poolse/sdk';
+export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, CallEndReason, CallLog, CallLogDisplay, CallLogEntry, CallLogMedia, CallMissedEntry, CallParticipantStatus, Conversation, ConversationCreateRequest, DeviceKind, LiveCall, LiveCallMember, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, ReadReceiptsState, RealtimeStatus, RoomSession, Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody } from '@poolse/sdk';
 import { ReactNode } from 'react';
 
 interface PoolseProviderProps {
@@ -549,11 +549,11 @@ interface UseCallRoom {
      * 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
+     * signal never hangs up, 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();
+     *       if (media.alone) room.leave();
      *     }, [media.alone]);
      */
     alone: boolean;
@@ -562,8 +562,7 @@ interface UseCallRoom {
      * Whether this deployment has an SFU.
      *
      * `null` until a join has been attempted, then `false` if the API
-     * answered 503. A `false` here is not a failure — it means fall back
-     * to `useVoiceRoom`, which is how every call worked before the SFU.
+     * answered 503: this deployment carries no call media.
      */
     sfuAvailable: boolean | null;
     /** Connect. Resolves `false` when there is no SFU. */
@@ -579,193 +578,19 @@ interface UseCallRoom {
 /**
  * A call's media, carried by the SFU.
  *
- * Media only. Ringing, accept/decline/hangup and the poolse roster stay
- * with `useCalls` and `useVoiceRoom`; this is what people sound and look
- * like. A call screen normally uses both.
+ * Media only — who is in the room and whether it is live come from
+ * `useRoom` / `useLiveCall`; this is what people sound and look like.
+ * `useRoom` wraps it.
  *
  *     const media = useCallRoom(conversationId, { livekit, video: true });
  *     await media.join();
  *     await media.toggleCamera();
  *
  * Both the camera and the microphone can be turned on and off at any
- * point during the call — that is the SFU's doing, since renegotiating a
- * live connection is exactly what the peer-to-peer mesh cannot do.
+ * point during the call.
  */
 declare function useCallRoom(conversationId: string | null, opts: UseCallRoomOptions): UseCallRoom;
 
-interface UseVoiceRoom {
-    status: VoiceStatus;
-    /** 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>;
-    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 & {
-    /** 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'
-/** 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;
-    /**
-     * What the current call opened as.
-     *
-     * `'audio'` when nothing is in flight. Either side can still turn
-     * their camera on mid-call — this is what was rung, which is what the
-     * incoming UI has to commit to before the user answers.
-     */
-    media: CallMedia;
-    error: Error | null;
-    /** Ring every other member of a conversation. */
-    call: (conversationId: string, media?: CallMedia) => Promise<void>;
-    /**
-     * Register a ring that arrived by some route other than the socket —
-     * in practice a VoIP push.
-     *
-     * Without this the push path shows a ring the state machine knows
-     * nothing about, and every signal that ends a call is guarded on
-     * state the machine never had: the caller hanging up sent
-     * `call:cancelled`, the guard found no matching `incoming`, and the
-     * callee's phone rang on until its own timeout.
-     *
-     * Idempotent per call id, because the socket almost always delivers
-     * the same call a moment later — that is one ring arriving twice, not
-     * a second caller.
-     */
-    ring: (call: IncomingCall) => void;
-    /**
-     * A call was torn down from outside this state machine.
-     *
-     * The counterpart to {@link ring}: the caller withdrew, or the call
-     * ended, and the news reached this device as a VoIP push rather than
-     * over the socket — which is the normal case for a phone that was
-     * asleep when the ring arrived and whose socket may not be up yet.
-     *
-     * Ignores call ids this client is not in, so a teardown for a
-     * previous call cannot end the current one.
-     */
-    dropped: (callId: string) => void;
-    /**
-     * Answer the inbound ring.
-     *
-     * Pass the call explicitly when it didn't arrive over the socket — a
-     * VoIP push can launch the app cold, in which case this hook has no
-     * `incoming` state and the push payload is the only source of truth.
-     */
-    accept: (call?: IncomingCall) => Promise<void>;
-    /** Reject the inbound ring. Takes an explicit call for the same
-     *  cold-launch reason as {@link accept}. */
-    decline: (call?: IncomingCall) => Promise<void>;
-    /** Hang up an outbound ring before it's answered. */
-    cancel: () => Promise<void>;
-    /**
-     * End the call, whatever state it is in.
-     *
-     * The one action a UI's hang-up button should call: it sends the right
-     * signal for the current phase — cancel while ringing out, decline
-     * while ringing in, hangup once connected — and always returns to
-     * idle, even if the signal fails. `reset` alone clears local state
-     * only, which leaves the other side in the call.
-     */
-    hangUp: () => 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;
-    /**
-     * Tell the hook how many OTHER people are currently on the call's
-     * media. `hangUp` consults it: with two or more others connected,
-     * hanging up just leaves — the call continues without you — and the
-     * end-the-call signal is only sent when at most one other remains.
-     * Every hang-up path funnels through the hook (the in-call button,
-     * CallKit's end event, the OS back gesture), so this is the ONE
-     * place group calls are protected from being ended by a leaver.
-     */
-    reportOthersOnCall: (count: number) => 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;
-
 interface UseLiveCall {
     /** The call running on the conversation right now, or null. */
     call: LiveCall | null;
@@ -783,6 +608,51 @@ interface UseLiveCall {
  */
 declare function useLiveCall(conversationId: string | null): UseLiveCall;
 
+interface UseRoomOptions {
+    /** `livekit-client`, imported by your app: `import * as livekit from 'livekit-client'`. */
+    livekit: LiveKitModule;
+}
+interface UseRoom {
+    /**
+     * The room (or call) running on the conversation right now, whether
+     * or not this user is in it — what a "Join" button reads.
+     */
+    live: ReturnType<typeof useLiveCall>['call'];
+    /** User ids in the room at this moment. */
+    presentIds: string[];
+    /** This user is in (or connecting to) the room. */
+    joined: boolean;
+    /** Starting or joining is in flight. */
+    joining: boolean;
+    /**
+     * Drop in: starts the conversation's room if none is live, or joins
+     * the one that is (a ringing call included). Nobody's phone rings.
+     * `video` turns the camera on as you arrive. `{ ring: true }` rings
+     * the other members' phones as well — an opt-in for apps where web
+     * calls people (a support desk); rooms never ring otherwise.
+     */
+    join: (media?: 'audio' | 'video', opts?: {
+        ring?: boolean;
+    }) => Promise<void>;
+    /** Leave. The room carries on for whoever is still in it. */
+    leave: () => void;
+    /** The media side: participants, mic/camera, devices (see `useCallRoom`). */
+    media: UseCallRoom;
+    error: Error | null;
+}
+/**
+ * A conversation's room — Meet-style: anyone in the conversation drops
+ * in for voice or video while the chat carries on, and nothing rings.
+ *
+ *     const room = useRoom(conversationId, { livekit });
+ *     room.live ? <button onClick={() => room.join()}>Join</button>
+ *               : <button onClick={() => room.join('video')}>Start a video room</button>;
+ *
+ * The room ends on its own once it has been empty for a short while,
+ * and leaves one line in the conversation's history.
+ */
+declare function useRoom(conversationId: string | null, opts: UseRoomOptions): UseRoom;
+
 interface UseReadReceipts {
     /**
      * Whether this user sees other people's read state. False → show no
@@ -822,4 +692,4 @@ declare function canEditOwnMessage(args: {
     now?: number;
 }): boolean;
 
-export { type CallPhase, EDIT_WINDOW_MS, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCallRoom, type UseCallRoomOptions, type UseCalls, type UseLiveCall, type UseReadReceipts, type UseUserState, type UseVoiceRoom, canEditOwnMessage, computeGroupPosition, formatDayLabel, receiptsOf, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCallRoom, useCalls, useConversation, useConversations, useLiveCall, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useReadReceipts, useRealtimeStatus, useThread, useTyping, useUser, useVoiceRoom };
+export { EDIT_WINDOW_MS, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCallRoom, type UseCallRoomOptions, type UseLiveCall, type UseReadReceipts, type UseRoom, type UseRoomOptions, type UseUserState, canEditOwnMessage, computeGroupPosition, formatDayLabel, receiptsOf, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCallRoom, useConversation, useConversations, useLiveCall, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useReadReceipts, useRealtimeStatus, useRoom, useThread, useTyping, useUser };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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, CameraFacing, CallDeviceKind, CallDevice, LiveKitModule, VoiceStatus, VoiceParticipant, VoiceRoomOptions, IncomingCall, OutgoingCall, CallMedia, LiveCall } from '@poolse/sdk';
-export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, CallEndReason, CallLog, CallLogDisplay, CallLogEntry, CallLogMedia, CallMissedEntry, CallParticipantStatus, Conversation, ConversationCreateRequest, DeviceKind, LiveCall, LiveCallMember, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, ReadReceiptsState, RealtimeStatus, Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody } from '@poolse/sdk';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput, PoolseUserProfile, CallRoomStatus, CallParticipant, CameraFacing, CallDeviceKind, CallDevice, LiveKitModule, LiveCall } from '@poolse/sdk';
+export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, CallEndReason, CallLog, CallLogDisplay, CallLogEntry, CallLogMedia, CallMissedEntry, CallParticipantStatus, Conversation, ConversationCreateRequest, DeviceKind, LiveCall, LiveCallMember, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, PoolseUserProfile, RateLimitedError, ReadReceiptsState, RealtimeStatus, RoomSession, Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody } from '@poolse/sdk';
 import { ReactNode } from 'react';
 
 interface PoolseProviderProps {
@@ -549,11 +549,11 @@ interface UseCallRoom {
      * 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
+     * signal never hangs up, 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();
+     *       if (media.alone) room.leave();
      *     }, [media.alone]);
      */
     alone: boolean;
@@ -562,8 +562,7 @@ interface UseCallRoom {
      * Whether this deployment has an SFU.
      *
      * `null` until a join has been attempted, then `false` if the API
-     * answered 503. A `false` here is not a failure — it means fall back
-     * to `useVoiceRoom`, which is how every call worked before the SFU.
+     * answered 503: this deployment carries no call media.
      */
     sfuAvailable: boolean | null;
     /** Connect. Resolves `false` when there is no SFU. */
@@ -579,193 +578,19 @@ interface UseCallRoom {
 /**
  * A call's media, carried by the SFU.
  *
- * Media only. Ringing, accept/decline/hangup and the poolse roster stay
- * with `useCalls` and `useVoiceRoom`; this is what people sound and look
- * like. A call screen normally uses both.
+ * Media only — who is in the room and whether it is live come from
+ * `useRoom` / `useLiveCall`; this is what people sound and look like.
+ * `useRoom` wraps it.
  *
  *     const media = useCallRoom(conversationId, { livekit, video: true });
  *     await media.join();
  *     await media.toggleCamera();
  *
  * Both the camera and the microphone can be turned on and off at any
- * point during the call — that is the SFU's doing, since renegotiating a
- * live connection is exactly what the peer-to-peer mesh cannot do.
+ * point during the call.
  */
 declare function useCallRoom(conversationId: string | null, opts: UseCallRoomOptions): UseCallRoom;
 
-interface UseVoiceRoom {
-    status: VoiceStatus;
-    /** 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>;
-    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 & {
-    /** 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'
-/** 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;
-    /**
-     * What the current call opened as.
-     *
-     * `'audio'` when nothing is in flight. Either side can still turn
-     * their camera on mid-call — this is what was rung, which is what the
-     * incoming UI has to commit to before the user answers.
-     */
-    media: CallMedia;
-    error: Error | null;
-    /** Ring every other member of a conversation. */
-    call: (conversationId: string, media?: CallMedia) => Promise<void>;
-    /**
-     * Register a ring that arrived by some route other than the socket —
-     * in practice a VoIP push.
-     *
-     * Without this the push path shows a ring the state machine knows
-     * nothing about, and every signal that ends a call is guarded on
-     * state the machine never had: the caller hanging up sent
-     * `call:cancelled`, the guard found no matching `incoming`, and the
-     * callee's phone rang on until its own timeout.
-     *
-     * Idempotent per call id, because the socket almost always delivers
-     * the same call a moment later — that is one ring arriving twice, not
-     * a second caller.
-     */
-    ring: (call: IncomingCall) => void;
-    /**
-     * A call was torn down from outside this state machine.
-     *
-     * The counterpart to {@link ring}: the caller withdrew, or the call
-     * ended, and the news reached this device as a VoIP push rather than
-     * over the socket — which is the normal case for a phone that was
-     * asleep when the ring arrived and whose socket may not be up yet.
-     *
-     * Ignores call ids this client is not in, so a teardown for a
-     * previous call cannot end the current one.
-     */
-    dropped: (callId: string) => void;
-    /**
-     * Answer the inbound ring.
-     *
-     * Pass the call explicitly when it didn't arrive over the socket — a
-     * VoIP push can launch the app cold, in which case this hook has no
-     * `incoming` state and the push payload is the only source of truth.
-     */
-    accept: (call?: IncomingCall) => Promise<void>;
-    /** Reject the inbound ring. Takes an explicit call for the same
-     *  cold-launch reason as {@link accept}. */
-    decline: (call?: IncomingCall) => Promise<void>;
-    /** Hang up an outbound ring before it's answered. */
-    cancel: () => Promise<void>;
-    /**
-     * End the call, whatever state it is in.
-     *
-     * The one action a UI's hang-up button should call: it sends the right
-     * signal for the current phase — cancel while ringing out, decline
-     * while ringing in, hangup once connected — and always returns to
-     * idle, even if the signal fails. `reset` alone clears local state
-     * only, which leaves the other side in the call.
-     */
-    hangUp: () => 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;
-    /**
-     * Tell the hook how many OTHER people are currently on the call's
-     * media. `hangUp` consults it: with two or more others connected,
-     * hanging up just leaves — the call continues without you — and the
-     * end-the-call signal is only sent when at most one other remains.
-     * Every hang-up path funnels through the hook (the in-call button,
-     * CallKit's end event, the OS back gesture), so this is the ONE
-     * place group calls are protected from being ended by a leaver.
-     */
-    reportOthersOnCall: (count: number) => 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;
-
 interface UseLiveCall {
     /** The call running on the conversation right now, or null. */
     call: LiveCall | null;
@@ -783,6 +608,51 @@ interface UseLiveCall {
  */
 declare function useLiveCall(conversationId: string | null): UseLiveCall;
 
+interface UseRoomOptions {
+    /** `livekit-client`, imported by your app: `import * as livekit from 'livekit-client'`. */
+    livekit: LiveKitModule;
+}
+interface UseRoom {
+    /**
+     * The room (or call) running on the conversation right now, whether
+     * or not this user is in it — what a "Join" button reads.
+     */
+    live: ReturnType<typeof useLiveCall>['call'];
+    /** User ids in the room at this moment. */
+    presentIds: string[];
+    /** This user is in (or connecting to) the room. */
+    joined: boolean;
+    /** Starting or joining is in flight. */
+    joining: boolean;
+    /**
+     * Drop in: starts the conversation's room if none is live, or joins
+     * the one that is (a ringing call included). Nobody's phone rings.
+     * `video` turns the camera on as you arrive. `{ ring: true }` rings
+     * the other members' phones as well — an opt-in for apps where web
+     * calls people (a support desk); rooms never ring otherwise.
+     */
+    join: (media?: 'audio' | 'video', opts?: {
+        ring?: boolean;
+    }) => Promise<void>;
+    /** Leave. The room carries on for whoever is still in it. */
+    leave: () => void;
+    /** The media side: participants, mic/camera, devices (see `useCallRoom`). */
+    media: UseCallRoom;
+    error: Error | null;
+}
+/**
+ * A conversation's room — Meet-style: anyone in the conversation drops
+ * in for voice or video while the chat carries on, and nothing rings.
+ *
+ *     const room = useRoom(conversationId, { livekit });
+ *     room.live ? <button onClick={() => room.join()}>Join</button>
+ *               : <button onClick={() => room.join('video')}>Start a video room</button>;
+ *
+ * The room ends on its own once it has been empty for a short while,
+ * and leaves one line in the conversation's history.
+ */
+declare function useRoom(conversationId: string | null, opts: UseRoomOptions): UseRoom;
+
 interface UseReadReceipts {
     /**
      * Whether this user sees other people's read state. False → show no
@@ -822,4 +692,4 @@ declare function canEditOwnMessage(args: {
     now?: number;
 }): boolean;
 
-export { type CallPhase, EDIT_WINDOW_MS, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCallRoom, type UseCallRoomOptions, type UseCalls, type UseLiveCall, type UseReadReceipts, type UseUserState, type UseVoiceRoom, canEditOwnMessage, computeGroupPosition, formatDayLabel, receiptsOf, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCallRoom, useCalls, useConversation, useConversations, useLiveCall, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useReadReceipts, useRealtimeStatus, useThread, useTyping, useUser, useVoiceRoom };
+export { EDIT_WINDOW_MS, type GroupPosition, PoolseProvider, type PoolseProviderProps, type ReactionMap, type UploadItem, type UploadItemStatus, type UseCallRoom, type UseCallRoomOptions, type UseLiveCall, type UseReadReceipts, type UseRoom, type UseRoomOptions, type UseUserState, canEditOwnMessage, computeGroupPosition, formatDayLabel, receiptsOf, sameDay, sameGroup, useAttachmentUpload, useAttachmentUrl, useCallRoom, useConversation, useConversations, useLiveCall, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useReadReceipts, useRealtimeStatus, useRoom, useThread, useTyping, useUser };