@elementaio/koine

@elementaio/koine

Zero-dependency TypeScript client for Koine embedded chat.

One WebSocket per device. Your backend mints a short-TTL JWT; you hand it to the client and it speaks the Koine wire protocol for you — idempotent sends with ack tracking, typed events, automatic reconnect with backoff, and exact cursor-based catch-up (it remembers the highest seq it has seen per conversation and re-syncs the gap on reconnect, once).

Runs in the browser and in Node 22+ — both expose a global WebSocket.

Install

npm install @elementaio/koine

Use

import { KoineClient } from "@elementaio/koine";

const koine = new KoineClient({
  url: "wss://chat.example.com/ws",
  token: jwtFromYourBackend,   // HS256, signed with the secret you share with Koine
  device: "web-1",             // stable per device → resumes cursors on reconnect
});

koine.on("message", (m) => render(m.conv, m.from, m.payload, m.seq));
koine.on("receipt", (r) => markRead(r.conv, r.from, r.seq));
koine.on("typing",  (t) => showTyping(t.conv, t.from));
koine.on("error",   (e) => console.warn("koine:", e.reason));

koine.connect();

// Idempotent send — the returned promise resolves with the durable seq.
const ack = await koine.send("general", "hello");
console.log("stored as seq", ack.seq);

// Live signals and read state:
koine.typing("general");
koine.read("general", ack.seq);
koine.presence("alice");

Reconnect & catch-up

By default the client reconnects on an unexpected drop (exponential backoff with jitter) and, once reconnected, re-syncs every conversation it has seen from its cursor — so you get exactly the messages you missed, once. After a full page reload, seed the cursors from your own persisted state first:

koine.setCursor("general", lastSeqYouRendered);
koine.connect();

API

Method	Purpose
connect() / close()	open the socket (reconnects are automatic) / close for good
send(conv, payload, { id?, kind? })	send; resolves with the ack (kind: "ephemeral" = live-only)
read(conv, seq)	advance your read watermark
typing(conv)	ephemeral typing signal
readState(conv, seq)	ask group read state (seen-by count)
presence(user)	ask if a user is online / last-seen
sync(conv, after?)	explicit catch-up (defaults to the tracked cursor)
cursor(conv) / setCursor(conv, seq)	read / seed catch-up state
on(event, handler) / off(...)	subscribe / unsubscribe
connected	is the socket open right now

Events: open, close, reconnecting, message, ack, receipt, sync_page, read_state, presence, system, typing, error — all typed.

Options

Option	Default	Meaning
url / token	(required)	gateway URL and the client JWT
device	random	stable device id; resumes this device's cursors
WebSocket	globalThis.WebSocket	inject an implementation if none is global
autoReconnect	true	reconnect on unexpected close
autoResync	true	re-sync tracked conversations on reconnect
reconnectBackoffMs	exp + jitter	(attempt) => ms schedule
ackTimeoutMs	10000	how long send() waits for its ack before rejecting

The full wire protocol is documented in docs/PROTOCOL.md.

Develop

npm install
npm test        # builds, then runs the node:test suite against a mock socket

License

MIT © Emad Jumaah