useRooms

Name: Flowstack
Author: Flowstack

hooksince 0.6.0

Hook: manage the built-app user's membership-scoped rooms — create, invite, claim, add, leave.

import { useRooms } from 'flowstack-sdk'

A room is a set of members with a server-enforced ACL. This hook manages MEMBERSHIP only; the room's DATA flows through useCollection({ layer: 'room', roomId }). Rooms are a built-app capability and require appScope on the provider config.

Every mutation refreshes myRooms on success, so the list stays current without a manual refresh().

Signature

useRooms(options?: { refreshInterval?: number; enabled?: boolean }): UseRoomsReturn

Parameters

Param	Type	Notes	Description
`options.refreshInterval`	`number`	—	Auto-poll interval in ms. Omitted = no polling (the default); the hook fetches once on mount and after each mutation.
`options.enabled`	`boolean`	—	Set `false` to skip the initial fetch and suppress polling (e.g. before the user is authenticated).

Returns

Field	Type	Description
`myRooms`	`string[]`	Room ids the caller is a member of.
`isLoading`	`boolean`	True while the room list is being fetched.
`error`	`string \| null`	Last error message, or null.
`refresh`	`() => Promise<void>`	Re-fetch the room list.
`createRoom`	`() => Promise<string \| null>`	Create a room (caller auto-added as first member). Returns the new room id, or null on failure.
`addMember`	`(roomId: string, userId: string) => Promise<boolean>`	Add a member by user id. The caller must already be a member.
`inviteMember`	`(roomId: string, email: string) => Promise<boolean>`	Pre-authorize an email to join. The caller must already be a member.
`claimInvites`	`() => Promise<string[]>`	Claim every pending invite addressed to the caller's verified email. Returns the joined room ids.
`leave`	`(roomId: string, userId?: string) => Promise<boolean>`	Leave a room, or revoke another member when `userId` is given.

Examples

Create a room and read its data

const { myRooms, createRoom, addMember } = useRooms();

const roomId = await createRoom();          // caller auto-added
if (roomId) await addMember(roomId, otherUserId);

// The room's DATA lives on useCollection, not here:
const { documents } = useCollection('notes', { layer: 'room', roomId: myRooms[0] });

Invite by email, then claim on the invitee’s next sign-in

// Existing member invites an email that may not have an account yet:
const { inviteMember } = useRooms();
await inviteMember(roomId, 'teammate@example.com');

// In the invitee's session, after sign-in:
const { claimInvites } = useRooms();
const joined = await claimInvites();   // ['room_abc', ...]

WarningRequires an appScope on the FlowstackProvider config — the SDK throws Rooms require an app scope (built-app context). before any network call if it is missing. The ACL is enforced server-side: the SDK never decides membership, so a client-side membership check is decoration, not security.

WarningAn invite grants no access until the invited user signs in and claims it. Call claimInvites() after authentication — nothing claims pending invites implicitly, so an app that never calls it leaves invited users locked out.

NoteaddMember takes a user id; inviteMember takes an email. Passing an email to addMember will not resolve to a user.

useRooms

Signature

Parameters

Returns

Examples

See also