@noverachat/sdk-web 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,86 @@
+[English](README.md) | [한국어](README.ko.md)
+
+# @noverachat/sdk-web
+
+NoveraChat용 최소·isomorphic(브라우저 + Node) TypeScript 클라이언트 — WebSocket + REST에 낙관적 UI, 재연결, backfill을 얹었다. 런타임 의존성 0.
+
+> [NoveraChat SDK 모노레포](../../README.md)의 한 패키지.
+
+## 설치
+
+```bash
+npm install @noverachat/sdk-web
+# 또는
+pnpm add @noverachat/sdk-web
+```
+
+Node ≥ 18 또는 최신 브라우저 필요 (플랫폼 `fetch` + `WebSocket` 사용).
+
+## 빠른 시작
+
+```ts
+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("편집됨", msg.message_id));
+room.on("messageDeleted", (e) => console.log("삭제됨", e.message_id));
+
+// 낙관적 전송 — 서버가 배정한 id로 resolve
+const { tempId, messageId } = await room.send("hello");
+
+// 읽음 처리(디바운스) + 모더레이션
+room.markRead(await messageId);
+await room.edit(await messageId, { content: "edited" });
+await room.react(await messageId, "emoji_heart");
+
+chat.disconnect();
+```
+
+단계별 안내는 [docs/getting-started/quickstart.ko.md](docs/getting-started/quickstart.ko.md) 참고.
+
+## 핵심 기능
+
+- **재연결 WebSocket** — 지수 백오프 + 지터, 재연결 금지 close code 존중
+- **낙관적 UI** — `ack` 시 `temp_id` → 서버 `message_id` 스왑, self-echo 중복 제거
+- **Backfill** — 재연결 후 놓친 메시지를 REST `?since=...`로 재수신
+- **읽음 워터마크 디바운스** — 기본 400ms, BigInt 비교로 단조 증가
+- **타입 있는 이벤트** — `MessageOut`, `ReactionEntry`, `ErrorCode` 등
+- **런타임 의존성 0** — Node·테스트용으로 `fetch` / `WebSocket` 주입 가능
+
+## 문서
+
+전체 문서는 [NoveraChat 문서 사이트](https://dev-chat-docs.novera.town/)에 발행되며, 같은 마크다운이 [`docs/`](docs/) 아래에 있고 여기서 sync된다.
+
+| 섹션                              | 내용                                                                    |
+| --------------------------------- | ----------------------------------------------------------------------- |
+| [시작하기](docs/getting-started/) | 설치, 퀵스타트                                                          |
+| [Core](docs/core/)                | 인증(`tokenProvider`), 연결 수명주기, 트랜스포트(REST vs WS), 유저 차단 |
+| [메시징](docs/messaging/)         | 전송, 수신, 편집/삭제, 리액션, 히스토리, 검색                           |
+| [룸](docs/rooms/)                 | 룸 파사드, 멤버, 모더레이션, 초대, 공지, 입력 중, 안읽음·읽음           |
+| [푸시](docs/push/)                | 디바이스 등록, 룸별 설정                                                |
+| [레퍼런스](docs/reference/)       | `NoveraChat` / `Room` API, 에러 코드                                    |
+
+### 컨트리뷰터용
+
+[`src/generated/`](src/generated/README.ko.md)의 와이어 타입은 [`@noverachat/protocol`](../protocol/README.ko.md)에서 **자동 생성**된다 — 손으로 고치지 말고, 스키마를 바꾼 뒤 `pnpm gen`.
+
+SDK를 _고치는_ 사람을 위한 내부 문서 — 발행 사이트엔 미포함:
+
+| 문서                                                                 | 내용                                                                                     |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [docs/internal/structure.ko.md](docs/internal/structure.ko.md)       | 무엇이 어디에 — 디렉토리·파일 지도, 파일별 책임, 읽기 순서                               |
+| [docs/internal/architecture.ko.md](docs/internal/architecture.ko.md) | 코드가 어떻게·왜 분해돼 있나 — 시스템 컨텍스트, 컴포넌트, 런타임 흐름, 설계 결정, 불변식 |
+
+## 상태
+
+Alpha. 서버 호환성: `protocol_version: "1.0"`

package/README.md

@@ -0,0 +1,86 @@
+[English](README.md) | [한국어](README.ko.md)
+
+# @noverachat/sdk-web
+
+Minimal, isomorphic (browser + Node) TypeScript client for NoveraChat — WebSocket + REST with optimistic UI, reconnection, and backfill. Zero runtime dependencies.
+
+> Part of the [NoveraChat SDK monorepo](../../README.md).
+
+## Install
+
+```bash
+npm install @noverachat/sdk-web
+# or
+pnpm add @noverachat/sdk-web
+```
+
+Requires Node ≥ 18 or a modern browser (uses platform `fetch` + `WebSocket`).
+
+## Quick start
+
+```ts
+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](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](https://dev-chat-docs.novera.town/); the same Markdown lives under [`docs/`](docs/) and is synced from here.
+
+| Section                                  | Contents                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [Getting started](docs/getting-started/) | Installation, quickstart                                                                    |
+| [Core](docs/core/)                       | Authentication (`tokenProvider`), connection lifecycle, transport (REST vs WS), user blocks |
+| [Messaging](docs/messaging/)             | Sending, receiving, editing/deleting, reactions, history, search                            |
+| [Rooms](docs/rooms/)                     | Room facade, members, moderation, invites, announcements, typing, unread & read receipts    |
+| [Push](docs/push/)                       | Device registration, per-room settings                                                      |
+| [Reference](docs/reference/)             | `NoveraChat` / `Room` API, error codes                                                      |
+
+### For contributors
+
+The wire types in [`src/generated/`](src/generated/README.md) are **auto-generated** from [`@noverachat/protocol`](../protocol/README.md) — 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](docs/internal/structure.md)       | What lives where — directory & file map, per-file responsibilities, reading order                          |
+| [docs/internal/architecture.md](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"`