Connect a frontend
@familiar-ai/client connects to the HTTP API, mirrors what its event streams send and derives the transcript a chat UI renders for a room. Familiar’s own web app is built on it.
npm install @familiar-ai/clientThe stores
Section titled “The stores”import { createRoomStore, createWorkspaceStore } from '@familiar-ai/client'import { getCurrentToken } from './host.ts'
const options = { // Every request, including stream reconnects, goes through this. fetch: async (input: RequestInfo | URL, init?: RequestInit) => { const request = new Request(input, init) request.headers.set('Authorization', `Bearer ${await getCurrentToken()}`) return fetch(request) },}const api = 'https://your-host.example/api'
// The workspace: who the Familiars are, and the rooms this person sees.const workspace = createWorkspaceStore(api, options)const [familiar] = await workspace.familiars.list()
// This person's DM with the first Familiar.const room = createRoomStore( api, await workspace.familiars.dm(familiar.id), options,)
const unsubscribe = room.subscribe((state) => { console.log(state.connection, state.transcript?.items.length)})
await room.send('Hello')
// On sign-out, or when this view goes away:unsubscribe()room.disconnect()workspace.disconnect()There’s a store for each stream: createWorkspaceStore(url, options) for who the Familiars are, the rooms this person sees and the sign-in; createFamiliarStore(url, id, options) for one Familiar’s model, memory and schedules; and createRoomStore(url, id, options) for one room. Each opens its stream straight away. A store offers every command; one your host’s allow refuses rejects with its 403, so render only the UI each person may use. The optional fetch makes every request, including stream reconnects, so you can attach a fresh credential each time. An open stream keeps the credentials it started with until it reconnects.
A store’s state is plain data from its stream. Read it with getState() and subscribe():
- the workspace’s
familiars,rooms,meandaccount: every room arrives as a sidebar lists it, with its newest entry, what this person hasn’t read and whose turns are in progress, so a list needs no stream per room - a Familiar’s
model,memoryandschedules - a room’s
view, its log;turns, its turns in progress; andtranscript, the derived chat items with any older entries loaded, whether a Familiar isbusyhere, and whetherearlierentries remain to load
Change things by calling the commands on the store itself: the workspace’s familiars, rooms, me, account, push, connections and mcp; a Familiar’s model, memory and schedules; a room’s send, stop, read and loadOlder. They never change identity, so you can pass them around freely. workspace.familiars.dm(id) resolves to the room ID of this person’s DM with a Familiar, created if new. Call a room’s read(entry) with the newest entry the person has seen, such as when they open it, to clear its unread count.
Streamed documents are undefined until they arrive, and null when the server sends none.
send(text, mentions?) posts a message with a fresh requestId. The host decides who sent it. In a named room, the message goes to the Familiars it mentions, or to everyone if it mentions none. Each Familiar decides whether to reply. composeMessage builds the text and mention spans from what a composer picked. Typing @Ada without picking her leaves the message unaddressed.
The transcript
Section titled “The transcript”state.transcript.items is what a chat shows, in order. Each item has an id that stays the same across updates. Use it as the key.
message: a person’s words, with theirauthor, when they were posted and anymentionsreply: a Familiar’stext,thinkingandtoolCalls, with whichfamiliarand itsname,streaming,stoppedand anyerrorscheduled: a schedule’s prompt arriving, with itsduetime andcreatorwaiting: a Familiar has a turn here with nothing to show yet:queuedbehind work in this room,elsewherewhile it works in another room, orrunningbefore its reply starts
While a reply streams, only its current round shows. When the turn ends, the whole reply, every tool call included, replaces it.
Each tool call has a name, arguments, status (running, done or error), text output and optional details. details is whatever the tool returned for UIs. Narrow it before you render it.
Older entries arrive through room.loadOlder() while transcript.earlier is true. It rejects if the page fails to load, so show its progress and failure where you call it.
The connection
Section titled “The connection”state.connection moves through these values:
| Value | Meaning |
|---|---|
connecting |
The first stream request is under way |
open |
A compatible protocol handshake has arrived; values follow |
reconnecting |
A network error, closed stream, 5xx or 429. The store retries with fresh state |
unauthorized |
The stream was answered 401 or 403. Retries stop |
failed |
Any other unusable answer, such as a 404. Retries stop |
outdated |
The protocol handshake was missing or incompatible. Retries stop |
The store never reloads the page or signs anyone in. After a terminal state, sign-out or an identity change, call store.disconnect() and create a new store. Commands reject with the server’s error and aren’t retried. Commands already sent still settle after you disconnect.
Install React 18 or 19, then use the separate /react entry:
import { createRoomStore } from '@familiar-ai/client'import { RoomProvider, useRoom, useRoomStore } from '@familiar-ai/client/react'
// Once, at module scope, for the room this page shows, such as one a host// made for everyone signed in. The provider never opens or closes the store.declare const roomId: numberconst store = createRoomStore('/api', roomId)
const Chat = () => { const connection = useRoom((state) => state.connection) const { send } = useRoomStore() const transcript = useRoom((state) => state.transcript)
if (connection !== 'open') { return <p>{connection}…</p> } return ( <> <ul> {transcript?.items.map((item) => ( <li key={item.id}> {item.type === 'message' && item.text} {item.type === 'reply' && item.text} </li> ))} </ul> <button onClick={() => void send('Hello')}>Say hello</button> </> )}
export const App = () => ( <RoomProvider store={store}> <Chat /> </RoomProvider>)Create the store once, outside render, where your app manages connections. RoomProvider gives its subtree a room store, and nested providers each give their own. The provider doesn’t open or close it. useRoom compares selections with Object.is, so return stable values such as a single field. useRoomStore() returns the nearest provider’s store, for its commands. For the workspace’s and Familiars’ stores, use Zustand’s useStore. The vanilla entry doesn’t load React.