@fkn/lib/rooms
Type Aliases
Section titled “Type Aliases”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.
Properties
Section titled “Properties”backlog
Section titled “backlog”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.
Parameters
Section titled “Parameters”number
limit?
Section titled “limit?”number
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<void>
claimed
Section titled “claimed”readonly claimed: boolean;whether an account keeps this name. Whether it keeps the messages too is mailbox.
closed
Section titled “closed”readonly closed: Promise<RoomEnd>;Settles once, when the room ends for this app. Never rejects.
defaults
Section titled “defaults”defaults: () => RoomDefaults;Returns
Section titled “Returns”delete
Section titled “delete”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.
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”number
string
envelope?
Section titled “envelope?”Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”string
permission
Section titled “permission”Returns
Section titled “Returns”Promise<void>
readonly id: string;<scope>/<name>: the name under this app’s own scope, or under global
invite
Section titled “invite”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.
Returns
Section titled “Returns”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.
Call Signature
Section titled “Call Signature”(maxMessageBytes, id?): Promise<void>;Parameters
Section titled “Parameters”maxMessageBytes
Section titled “maxMessageBytes”number
string
Returns
Section titled “Returns”Promise<void>
Call Signature
Section titled “Call Signature”(maxMessageBytes, id): Promise<void>;Parameters
Section titled “Parameters”maxMessageBytes
Section titled “maxMessageBytes”number | null
string
Returns
Section titled “Returns”Promise<void>
mailbox
Section titled “mailbox”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
Section titled “members”members: () => Promise<RoomMember[]>;Returns
Section titled “Returns”readonly name: string;on: (listener) => Promise<() => void>;Await the returned unsubscribe in cleanup, the account.onChange shape.
Parameters
Section titled “Parameters”listener
Section titled “listener”(event) => void
Returns
Section titled “Returns”Promise<() => void>
readonly owner: string;the owner’s member id, or ” while a claimed room’s owner has never joined
release
Section titled “release”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.
Returns
Section titled “Returns”Promise<void>
remove
Section titled “remove”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
revoke
Section titled “revoke”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.
Parameters
Section titled “Parameters”string
permission
Section titled “permission”Returns
Section titled “Returns”Promise<void>
schema
Section titled “schema”schema: () => RoomSchema | null;the room’s schema as the room last said, null for a room without one
Returns
Section titled “Returns”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.
Parameters
Section titled “Parameters”string
envelope?
Section titled “envelope?”Returns
Section titled “Returns”Promise<void>
setDefault
Section titled “setDefault”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.
Parameters
Section titled “Parameters”permission
Section titled “permission”"send" | "receive"
boolean
Returns
Section titled “Returns”Promise<void>
setMailbox
Section titled “setMailbox”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.
Parameters
Section titled “Parameters”boolean
Returns
Section titled “Returns”Promise<void>
setSchema
Section titled “setSchema”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).
Parameters
Section titled “Parameters”schema
Section titled “schema”Returns
Section titled “Returns”Promise<void>
unblock
Section titled “unblock”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
usage: () => Promise<RoomMailbox | null>;Returns
Section titled “Returns”Promise<RoomMailbox | null>
RoomsError
Section titled “RoomsError”type RoomsError = Error & object;Thrown by every member of this namespace. Match on code, never on the message.
Type Declaration
Section titled “Type Declaration”code: RoomsErrorCode;Functions
Section titled “Functions”available()
Section titled “available()”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.
Returns
Section titled “Returns”Promise<boolean>
create()
Section titled “create()”function create(options?): Promise<Room>;Open a room under a random name and become its owner. Share room.invite to let anyone else in.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”join()
Section titled “join()”function join(invite, options?): Promise<Room>;invite is room.invite: a key and a room id joined by a dot.
Parameters
Section titled “Parameters”invite
Section titled “invite”string
options?
Section titled “options?”Returns
Section titled “Returns”open()
Section titled “open()”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.
Parameters
Section titled “Parameters”string
options?
Section titled “options?”Returns
Section titled “Returns”References
Section titled “References”ClaimOptions
Section titled “ClaimOptions”Renames and re-exports RoomClaimOptions
CreateOptions
Section titled “CreateOptions”Renames and re-exports RoomCreateOptions
JoinOptions
Section titled “JoinOptions”Renames and re-exports RoomJoinOptions
OpenOptions
Section titled “OpenOptions”Renames and re-exports RoomOpenOptions
RoomBacklog
Section titled “RoomBacklog”Re-exports RoomBacklog
RoomDefaults
Section titled “RoomDefaults”Re-exports RoomDefaults
RoomEnd
Section titled “RoomEnd”Re-exports RoomEnd
RoomEnvelope
Section titled “RoomEnvelope”Re-exports RoomEnvelope
RoomEvent
Section titled “RoomEvent”Re-exports RoomEvent
RoomJson
Section titled “RoomJson”Re-exports RoomJson
RoomMailbox
Section titled “RoomMailbox”Re-exports RoomMailbox
RoomMember
Section titled “RoomMember”Re-exports RoomMember
RoomMessage
Section titled “RoomMessage”Re-exports RoomMessage
RoomPermission
Section titled “RoomPermission”Re-exports RoomPermission
RoomPermissions
Section titled “RoomPermissions”Re-exports RoomPermissions
RoomSchema
Section titled “RoomSchema”Re-exports RoomSchema
RoomsErrorCode
Section titled “RoomsErrorCode”Re-exports RoomsErrorCode
RoomType
Section titled “RoomType”Re-exports RoomType