English | 한국어

@noverachat/sdk-web

Minimal, isomorphic (browser + Node) TypeScript client for NoveraChat — WebSocket + REST with optimistic UI, reconnection, backfill, core-owned message state (MessageCollection) and an app-injectable snapshot cache for instant cold starts. Zero runtime dependencies.

Part of the NoveraChat SDK monorepo.

Install

npm install @noverachat/sdk-web
# or
pnpm add @noverachat/sdk-web

Requires Node ≥ 18 or a modern browser (uses platform fetch + WebSocket).

Quick start

import { NoveraChat } from "@noverachat/sdk-web";

const chat = new NoveraChat({
  appId: "app_9f8k2x",
  endpoint: "https://chat.example.com",
  tokenProvider: async () => fetchJwtFromYourServer(),
});

await chat.connect();

const room = chat.room("room_123");

room.on("message", (msg) => console.log(msg.content));
room.on("messageUpdated", (msg) => console.log("edited", msg.message_id));
room.on("messageDeleted", (e) => console.log("deleted", e.message_id));

// optimistic send — resolves with the server-assigned id
const { tempId, messageId } = await room.send("hello");

// read receipt (debounced) + moderation
room.markRead(await messageId);
await room.edit(await messageId, { content: "edited" });
await room.react(await messageId, "emoji_heart");

chat.disconnect();

See docs/getting-started/quickstart.md for a step-by-step walkthrough.

Key features

• Reconnecting WebSocket — exponential backoff + jitter, honours no-reconnect close codes
• Optimistic UI — temp_id → server message_id swap on ack, with self-echo dedup
• Backfill — re-fetch missed messages via REST ?since=... after reconnect
• Read-watermark debouncing — 400ms default window, monotonic (BigInt-compared)
• Typed events — MessageOut, ReactionEntry, ErrorCode, and more
• Zero runtime deps — pluggable fetch / WebSocket for Node and testing

Documentation

The full docs are published on the NoveraChat docs site; the same Markdown lives under docs/ and is synced from here.

| Section | Contents | | ---------------------------------------- | ------------------------------------------------------------------------------------------- | | Getting started | Installation, quickstart | | Core | Authentication (tokenProvider), connection lifecycle, transport (REST vs WS), user blocks | | Messaging | Sending, receiving, editing/deleting, reactions, history, search | | Rooms | Room facade, members, moderation, invites, announcements, typing, unread & read receipts | | Push | Device registration, per-room settings | | Reference | NoveraChat / Room API, error codes |

For contributors

The wire types in src/generated/ are auto-generated from @noverachat/protocol — don't hand-edit them; change the schema and run pnpm gen.

Internal docs for people working on the SDK — not part of the published site:

| Doc | Contents | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | docs/internal/structure.md | What lives where — directory & file map, per-file responsibilities, reading order | | docs/internal/architecture.md | How the code is decomposed & why — system context, components, runtime flows, design decisions, invariants |

Status

Alpha. Server compatibility: protocol_version: "1.0"