@kispi/chat

Client SDK for the chat server. Many rooms over one socket, history in the right order. Zero runtime dependencies, both ESM and CJS, type declarations included.

There are two entry points. @kispi/chat is the client for the browser and Node; @kispi/chat/server is for the consumer backend that holds the sk_.

npm install @kispi/chat

This document covers the entire surface. Anything not here is internal and changes without notice.

#@kispi/chat — client

#createChatClient(options): ChatClient

Do not create token in the browser. Signing requires the sk_, and if the sk_ is in the browser, the whole app is open.

#ChatClient

on returns an unsubscribe function.

const off = chat.on('state', s => setStatus(s))
off()

#Room

Event names are exactly the wire names, and the payloads are in the type declarations.

The SDK emits three more that have no wire counterpart.

#Things to know

messages is a new array every time, and only changed rows are new objects. Put it straight into state that compares by reference.

// Svelte 5
let messages = $state.raw<Message[]>([])
room.on('messages', m => (messages = m))

// React
const [messages, setMessages] = useState<Message[]>([])
useEffect(() => room.on('messages', setMessages), [room])

// Vue
const messages = shallowRef<Message[]>([])
room.on('messages', m => (messages.value = m))

• Don't ignore reset. If you keep appending to the old list, you're left with a gap that nobody fills.

• Attach the past to the same list with loadOlder(). history() is a direct read that doesn't touch the list, so merging and deduplicating fall to you.

• typing is also delivered to the sender. If you render "X is typing", skip your own userId.

• typing carries no name. Look the name up in room.presence.users — whoever is watching the room is there. Collecting names from message senders misses anyone who has not spoken yet. If users is absent (a room over 100), fetch it once with presenceList(), and fall back to a placeholder if the name is still missing.

  ts

  room.on('typing', ({ userId }) => {
    if (userId === chat.user?.id) return
    const name = room.presence?.users?.find(u => u.id === userId)?.name
    showTyping(userId, name ?? 'Someone')   // clearing it after a few seconds is yours to do
  })

• The connection comes back on its own. It reconnects with exponential backoff, so don't write your own retry loop.

• What you send while reconnecting waits, then goes out. send, react, unreact and markRead skip the backoff when the state is connecting/reconnecting, wait for the connection, and send. If the socket drops before the ack, the same frame is sent once more — the server dedups on clientMessageId, and reactions and reads are idempotent, so nothing lands twice. Waiting plus the ack is capped at 15 seconds, then timeout. closed now comes only from a stopped client (close(), an auth refusal, or never connect()ed). typing() does not wait; it is dropped.

• The SDK handles token expiry. When REST gets a 401 it calls token() again and retries once. There's no need to reconnect periodically.

• Throwing a ChatError from token() stops the client. That is how you say a failure, like a ban, is not worth retrying.

• After a nickname or avatar change, reconnect(). The server reads those values from the token claims once, when the socket authenticates.

#text is untrusted plain text

Message text, and user-supplied display names/nicknames (name), are plain text the engine does not HTML-escape or sanitize. This is by design — escaping depends on the output context you render into (an HTML text node, an attribute, some other format), which the engine cannot decide on your behalf. The engine only validates (size, shape).

So consumers must render it as text — textContent, or your framework's text binding (React's {text}, Svelte's {text}, Vue's {{ text }}). Never pass it straight into innerHTML or v-html. If you add linkification or markup, don't build an HTML string with a regex replace — build DOM from text nodes instead.

// Don't — builds an HTML string with a regex
el.innerHTML = text.replace(urlRegex, '<a href="$1">$1</a>')

// Do — builds DOM from text nodes
for (const part of splitByUrl(text)) {
  el.appendChild(part.isUrl ? makeAnchor(part.text) : document.createTextNode(part.text))
}

Bad-word filtering and similar moderation is not escaping — it's a tenant policy. The engine only opens the mechanism (the before_publish hook); the consumer decides (see the before_publish section in docs/protocol.md).

#Using it in the browser

You must add the page's origin to the pk_'s allowed origins. That's the only thing — the server emits CORS headers itself, so there's no proxy to touch. Origins are edited on the key screen in the console.

Scheme, host and port must match exactly. https://example.com and https://www.example.com, http://localhost:3000 and http://127.0.0.1:3000 are different origins. Add development origins separately.

From an origin that isn't on the list it isn't just REST that fails — the connection itself is a 401. An authentication refusal is a failure the SDK doesn't retry, so the client stops at closed, and the reason arrives on chat.on('error').

#Errors

Failures are ChatError.

try {
  await room.send({ text })
} catch (err) {
  if (err instanceof ChatError && err.code === 'rate_limited') {
    retryAfter(err.retryAfterMs)
  }
}

#@kispi/chat/server — backend

Uses the sk_. Never put it in the browser.

import { createChatServer } from '@kispi/chat/server'

const chat = createChatServer({
  secretKey: process.env.CHAT_SECRET_KEY!,      // sk_…
  webhookSecret: process.env.CHAT_WEBHOOK_SECRET,
  guestSecret: process.env.CHAT_GUEST_SECRET,   // only if you use guest()
})

#chat.token(input): string

A local signature that doesn't touch the network.

#chat.guest({credential?, name, avatar?, meta?, ttlSeconds?})

Identity for a visitor who isn't logged in. Returns {userId, credential, token, created}. Uses neither the network nor storage.

app.post('/api/chat-token', (req, res) => {
  if (req.user) return res.json({ token: chat.token({ userId: req.user.id, name: req.user.name }) })
  const g = chat.guest({ credential: req.cookies.chat_guest, name: 'Guest' })
  res.cookie('chat_guest', g.credential, { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 400 * 864e5 })
  res.json({ token: g.token })
})

Never sign a userId handed back by the browser as-is. guest() has the browser hold a credential instead of the id — if it verifies, it signs with the id inside it; if it's missing or invalid, it signs a new guest (created: true). Keep it in an httpOnly cookie where you can.

Guest ids start with g_. As long as logged-in users' ids don't start with g_, the two spaces don't overlap.

#The rest

rooms.list returns the app's rooms, newest first. With no type it is the public listing (public and channel); pass e.g. type: ['private', 'dm'] for private rooms and DMs. limit defaults to 50 (max 100), an empty cursor is the last page, and the cursor does not carry type — start over when the filter changes.

rooms.ensure is get-or-create — it returns the room as-is if it exists, so it's fine to call on every page load.

rooms.presence(roomId) is {count}; with {full: true} it adds users (at most 1000, capped: true when cut). An empty room is {count: 0}, not a 404.

rooms.custom(roomId, payload) is a control signal that is not stored. payload is a JSON object and arrives as-is at room.on('custom', ...). It leaves no history, no unread and no webhook, so send a signal that must survive a reconnect with messages.send(roomId, {kind:'system', ...}) instead.

users.ban's until is unix milliseconds and required. For an indefinite ban, pick a far-future time yourself.

users.purgeMessages(userId) clears that user's messages without withdrawing them. It does a bounded amount per call, so call again while purgeCapped is true, and for spam ban first.

await chat.users.ban(userId, { until: Date.now() + 7 * 86_400_000, reason: 'spam' })
while ((await chat.users.purgeMessages(userId)).purgeCapped) {}

users.list is newest first, limit defaults to 50 and maxes at 100, and cursor is an opaque string where an empty string marks the last page. Withdrawn users are included too, and deletedAt marks them. users.* works only after the person has connected at least once — users come into existence by connecting.

#Webhooks

app.post('/chat-hook', express.raw({ type: 'application/json' }), (req, res) => {
  const { event, delivery, data } = chat.webhooks.verify(req.headers, req.body.toString('utf8'))
  if (seen.has(delivery)) return res.sendStatus(200)  // it's at-least-once
  res.sendStatus(200)                                  // acknowledge first
  void handle(event, data)                             // process asynchronously
})

It must be the raw body. Something parsed and re-serialized is a different string and fails verification.

Keep three things. verify checks the signature and the timestamp (default 5 minutes), deduplication is on you (by delivery), and you must respond with a 2xx within 10 seconds. Going over counts as a failure and backoff begins.

The signature spec for other languages is in the webhooks guide.