Skip to content

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.

Terminal window
npm install @familiar-ai/client
client.ts
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, me and account: 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, memory and schedules
  • a room’s view, its log; turns, its turns in progress; and transcript, the derived chat items with any older entries loaded, whether a Familiar is busy here, and whether earlier entries 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.

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 their author, when they were posted and any mentions
  • reply: a Familiar’s text, thinking and toolCalls, with which familiar and its name, streaming, stopped and any error
  • scheduled: a schedule’s prompt arriving, with its due time and creator
  • waiting: a Familiar has a turn here with nothing to show yet: queued behind work in this room, elsewhere while it works in another room, or running before 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.

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:

App.tsx
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: number
const 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.