Skip to content

@fkn/lib/rooms

type Room = object;

A joined room. The same object survives a broker replacement, so it is safe to hold for as long as the chat lasts.

backlog: (after, limit?) => Promise<RoomBacklog>;

replays the stored messages above after as message events, one page at a time: at most limit messages and never more than 200 or 64 KiB, though a page holds one while any is left. They come in seq order, all of them before the call resolves, so a list built from them is whole once it does. replayed marks the ones that predate this connection, so one sent since comes again unmarked: key a list by seq. A message that does not open under the room’s key is skipped. last is the seq the next page starts after, and more whether the room holds messages past it. Refused denied (rooms: permission denied) without receive.

number

number

Promise<RoomBacklog>

block: (id) => Promise<void>;

sends a member out of the room and keeps them out, with the block permission (denied, rooms: permission denied). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

string

Promise<void>

claim: (options?) => Promise<void>;

keeps the name for the signed-in account, and a mailbox unless asked not to. A free account holds 5 claims and a premium one 10, in any scope, global included; once premium lapses the account keeps its 5 oldest claims and the others are released 30 days later. description says what the room is for, shown to the account in its fkn.app settings; a permanent claim with an unchanged one on every open is free. Claiming on every open also claims the room again after the account unclaims it from fkn.app, so claim when the person wants the room kept, or make it temporary.

temporary makes the claim end by itself, in milliseconds (true is 7 days), that long after its last claim: a temporary claim goes to the account’s ledger every time, which is what restarts its clock. When it ends the app hears a claim event with claimed: false, exactly as for an Unclaim from fkn.app, and the stored messages are gone. A broker too old to carry it refuses the call unavailable (rooms: temporary claims are not available) rather than make the claim permanent.

mailbox: false keeps the name and stores nothing: the room relays as an unclaimed one does. It is read only when the call starts the claim and ignored on a room the account already holds, so claiming on every open never undoes the owner’s choice.

Who changes a claimed room depends on its scope. A room under an app’s scope, which is every room but a global one, is changed by the claim’s account only through the app that claimed it (the same app once it is verified): from another app of the account setDefault, limit, grant, revoke, remove, block, unblock, setMailbox, edit and delete are refused denied (rooms: only the app that claimed the room can change it), the account’s own messages included, and nothing changes. That other app, which reaches the room through its invite, still joins, reads and sends. A claimed global room is changed by any app of the account, which also describes it, sets its temporary and releases it. The account changes every room it claimed from its fkn.app settings, whichever app claimed it, and members of other accounts are answered as in any room. While the room cannot tell whether two apps are one, such a change is refused unavailable (rooms: rooms are unavailable) and can be sent again.

Past the account’s room limit the call waits while fkn.app shows the person their claimed rooms over your app, with Unclaim on each: it resolves once one is unclaimed and this claim is made, and rejects full (rooms: too many claims) when they close the card or when fkn.app cannot show it. Nothing about the account’s other rooms reaches your app.

RoomClaimOptions

Promise<void>

readonly claimed: boolean;

whether an account keeps this name. Whether it keeps the messages too is mailbox.

readonly closed: Promise<RoomEnd>;

Settles once, when the room ends for this app. Never rejects.

defaults: () => RoomDefaults;

RoomDefaults

delete: (from, to?) => Promise<void>;

drops stored messages: one of your own, or any range as the owner. On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), the account’s own messages included, as claim says.

number

number

Promise<void>

edit: (seq, text, envelope?) => Promise<void>;

replaces a stored message’s text: one of your own, or any as the owner. Checked exactly as a send is, send and the rate limits included; in a room with a schema envelope is required and names the message’s own type, so a message stored before the room had a schema is deleted rather than edited. On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), the account’s own messages included, as claim says.

number

string

RoomEnvelope

Promise<void>

grant: (id, permission) => Promise<void>;

gives a member a permission over the room default, from the owner only (denied, rooms: not the room owner). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

string

RoomPermission

Promise<void>

readonly id: string;

<scope>/<name>: the name under this app’s own scope, or under global

readonly invite: string;

key and id as one string, the thing to put in a link

readonly key: string;

the room key, base64url. The server never sees it. Anyone holding it and the id can join.

leave: () => Promise<void>;

ends this Room: closed settles with left, and later requests are refused closed (rooms: the room has ended). The room counts members, not Rooms: an account whose key this device holds is one member in all of its tabs, apps and devices, and a guest, or a tab without the account’s key, is one member in that tab and in any tab duplicated from it. While another Room of the same member is open the member stays and nobody present hears a thing; the last one’s leave is the departure, a left event with reason left for everyone else.

Promise<void>

limit: {
(maxMessageBytes, id?): Promise<void>;
(maxMessageBytes, id): Promise<void>;
};

the message size cap, from 1 to 31,457,280 (30 MiB). With no id it sets the room default, which is always a number. With an id it sets that member’s override, and null clears the override. From the owner only (denied, rooms: not the room owner); on a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

(maxMessageBytes, id?): Promise<void>;

number

string

Promise<void>

(maxMessageBytes, id): Promise<void>;

number | null

string

Promise<void>

readonly mailbox: RoomMailbox | null;

what the mailbox holds, as the room last said. Null while the room keeps no messages: nobody has claimed it, or its claim keeps none. The account can clear the room, unclaim it, turn its messages off or on, or set a lower cap from its fkn.app settings, which the app hears as a deleted or a claim event; usage() reads the figures again.

members: () => Promise<RoomMember[]>;

Promise<RoomMember[]>

readonly name: string;
on: (listener) => Promise<() => void>;

Await the returned unsubscribe in cleanup, the account.onChange shape.

(event) => void

Promise<() => void>

readonly owner: string;

the owner’s member id, or ” while a claimed room’s owner has never joined

release: () => Promise<void>;

gives the claim back: the mailbox is deleted and whoever is present stays in an ordinary room. On a room under an app’s scope, the app that claimed it only (the same app once it is verified), and from another app it is refused denied (rooms: only the app that claimed the room can release it); on a global room, any app of the account. The account can also unclaim it from its fkn.app settings.

Promise<void>

remove: (id) => Promise<void>;

sends a member out of the room, which they may join again, with the remove permission (denied, rooms: permission denied). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

string

Promise<void>

revoke: (id, permission) => Promise<void>;

takes a permission from a member over the room default, from the owner only (denied, rooms: not the room owner). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

string

RoomPermission

Promise<void>

schema: () => RoomSchema | null;

the room’s schema as the room last said, null for a room without one

RoomSchema | null

readonly self: RoomMember;

this app’s member record, as this room sees it. The id is fresh in every room.

send: (text, envelope?) => Promise<void>;

text is sealed before it leaves the browser. Rejects too-large past self.maxMessageBytes on the wire, never truncates.

In a room with a schema envelope is required: it goes in plain beside the sealed text, which may be empty, and the sealed text opens only under it. The app chooses what is sealed at each send: put in the envelope only what every member and FKN may read, and the rest in text. The lib writes it with JSON.stringify and refuses invalid (rooms: the message does not fit the room's schema), with nothing sent, one that is not a JSON object with a string type or is past 2,048 characters; the room refuses the same for an envelope that does not fit its type, or a send without one. The size counted is the envelope’s text and the sealed text together, against self.maxMessageBytes and the type’s maxBytes. The type’s sender rule refuses denied (rooms: only the owner sends this type, rooms: sending this needs an account), its per-account limit full (rooms: you have as many of these here as the room allows), and the room’s cap storage (rooms: the mailbox is full).

Without a schema an envelope is refused invalid (rooms: the room has no schema). An fkn.app older than room schemas refuses one unavailable (rooms: room schemas are not available) with nothing sent; a send without one goes as before.

string

RoomEnvelope

Promise<void>

setDefault: (permission, value) => Promise<void>;

whether a member with no override may send or receive, from the owner only (denied, rooms: not the room owner). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

"send" | "receive"

boolean

Promise<void>

setMailbox: (on) => Promise<void>;

turns a claimed room’s mailbox off or on, from the room’s owner only, which in a claimed room is the claim’s account. Off deletes every stored message at once, the archive included, and the room then relays as an unclaimed one does while keeping its claim; whoever is present hears a claim event with mailbox: false and no deleted, so what an app shows stays. On starts an empty mailbox that keeps messages from the next seq, and nothing deleted comes back. Neither way needs premium. Setting what it already is changes nothing. Resolves once the room answered, with mailbox reading the new state, or a newer one when a release or the account’s own switch landed before the answer.

Refused invalid (rooms: the room is not claimed) on an unclaimed room, denied (rooms: not the room owner) from anyone else, denied (rooms: only the app that claimed the room can change it) from another app of the claim’s account on a room claimed under an app’s scope, as claim says, and invalid (rooms: malformed frame) for anything but a boolean. A broker too old to carry it refuses unavailable (rooms: the mailbox switch is not available). The account can do the same from its fkn.app settings, whichever app claimed the room.

boolean

Promise<void>

setSchema: (schema) => Promise<void>;

replaces the room’s schema with one of a higher version, from the next send on; everyone present hears a schema event. The same schema at the same version resolves and changes nothing, so set it on every open. A lower version, or another schema at the same one, is refused invalid (rooms: the room holds a newer schema), and one the room cannot take invalid (rooms: the schema is not one a room can take). From the owner only (denied, rooms: not the room owner), and on a room claimed under an app’s scope only through the app that claimed it (denied, rooms: only the app that claimed the room can change it), as claim says. A schema is never removed. An fkn.app older than room schemas refuses it unavailable (rooms: room schemas are not available).

RoomSchema

Promise<void>

unblock: (id) => Promise<void>;

lets a blocked member join again, with the block permission (denied, rooms: permission denied). On a room claimed under an app’s scope, from another app of the claim’s account, it is refused denied (rooms: only the app that claimed the room can change it), as claim says.

string

Promise<void>

usage: () => Promise<RoomMailbox | null>;

Promise<RoomMailbox | null>


type RoomsError = Error & object;

Thrown by every member of this namespace. Match on code, never on the message.

code: RoomsErrorCode;
function available(): Promise<boolean>;

Whether this realm can join a room: false in Node, false in a worker nothing bridged, false against a shell older than named rooms. Answers rather than rejecting.

Promise<boolean>


function create(options?): Promise<Room>;

Open a room under a random name and become its owner. Share room.invite to let anyone else in.

RoomOpenOptions

Promise<Room>


function join(invite, options?): Promise<Room>;

invite is room.invite: a key and a room id joined by a dot.

string

RoomJoinOptions

Promise<Room>


function open(name, options?): Promise<Room>;

Open a room by name: a name under this app’s own scope, or global/<name> for the shared one. Nobody there means the room comes into being with you as its owner; somebody there means you join them, and the key has to match theirs. Share room.invite to let anyone else in.

string

RoomOpenOptions

Promise<Room>

Renames and re-exports RoomClaimOptions


Renames and re-exports RoomCreateOptions


Renames and re-exports RoomJoinOptions


Renames and re-exports RoomOpenOptions


Re-exports RoomBacklog


Re-exports RoomDefaults


Re-exports RoomEnd


Re-exports RoomEnvelope


Re-exports RoomEvent


Re-exports RoomJson


Re-exports RoomMailbox


Re-exports RoomMember


Re-exports RoomMessage


Re-exports RoomPermission


Re-exports RoomPermissions


Re-exports RoomSchema


Re-exports RoomsErrorCode


Re-exports RoomType