@noverachat/sdk-react 0.3.0

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,99 @@
+# @noverachat/sdk-react
+
+> 🇺🇸 [English](./README.md)
+
+NoveraChat용 React 훅/바인딩 — [`@noverachat/sdk-web`](../sdk-web)(헤드리스 `NoveraChat` / `Room` 코어) 위의 얇은 레이어. 채팅 로직을 재구현하지 않고 채팅 UI도 제공하지 않는다 — 이 패키지는 글루만 담당한다: 라이프사이클을 관리하는 프로바이더와, SDK 이벤트를 React 상태로 옮기는 훅들.
+
+## 설치
+
+```sh
+npm i @noverachat/sdk-react @noverachat/sdk-web react
+```
+
+`react >= 18` peer dependency (`useSyncExternalStore` 사용).
+
+## 빠른 시작
+
+```tsx
+import {
+  NoveraChatProvider,
+  useMessages,
+  useTyping,
+} from "@noverachat/sdk-react";
+
+function App() {
+  return (
+    <NoveraChatProvider
+      options={{
+        appId: "app_9f8k2x",
+        endpoint: "https://chat.example.com",
+        tokenProvider: async () => fetchJwt(),
+      }}
+    >
+      <ChatScreen roomId="room_123" />
+    </NoveraChatProvider>
+  );
+}
+
+function ChatScreen({ roomId }: { roomId: string }) {
+  const { messages, hasMore, store } = useMessages(roomId);
+  const { isAnyoneTyping, setTyping } = useTyping(roomId);
+
+  return (
+    <>
+      {hasMore && <button onClick={() => store.loadMore()}>이전 대화…</button>}
+      {messages.map((m) => (
+        <div key={m.id}>
+          {m.isDeleted ? "(삭제됨)" : m.content}
+          {m.status === "sending" && " ⏳"}
+          {m.status === "failed" && " ⚠️"}
+        </div>
+      ))}
+      {isAnyoneTyping && <span>입력 중…</span>}
+      <input
+        onChange={() => setTyping(true)}
+        onKeyDown={(e) => {
+          if (e.key !== "Enter") return;
+          store.send(e.currentTarget.value);
+          e.currentTarget.value = "";
+        }}
+      />
+    </>
+  );
+}
+```
+
+## API
+
+| Export | 설명 |
+|---|---|
+| `NoveraChatProvider` / `useNoveraChat()` | `NoveraChat`을 생성하고 마운트 라이프사이클에 맞춰 `connect()`/`disconnect()`를 실행. 하위 어디서든 훅으로 클라이언트를 읽는다. options는 **최초 1회만** 읽힌다 — 다른 옵션으로 재접속하려면 새 `key`로 리마운트. |
+| `useRoom(roomId)` | `Room` 파사드. 훅이 커버하지 않는 SDK 직접 호출용 (멤버, 공지, 초대 링크, 모더레이션 등). |
+| `useMessages(roomId, opts?)` | 라이브 메시지 리스트(`ChatMessage[]`, 오래된 순) + `hasMore` + `readWatermarks`, 그리고 액션용 `RoomStore`: `send`, `sendFile`(업로드 진행률), `edit`, `delete`, `toggleReaction`, `markRead`, `loadMore`, `search`, `isReadBy`, `readCount`. 전송은 낙관적 — `sending` 버블이 ack에 `sent`로, 실패 시 `failed`로 바뀐다. |
+| `useTyping(roomId, opts?)` | 입력 중인 사용자 목록(`timeoutMs`, 기본 5초 후 자동 만료) + 내 입력 상태를 브로드캐스트하는 `setTyping`. |
+| `useUnread(opts?)` | 계정 전체 안읽음 뱃지: `total`, 방별 `summary`, `refresh()`, 선택적 `refreshIntervalMs` 폴링. |
+| `useRoomList(opts?)` | 라이브 채팅방 리스트(채팅 탭): 프리뷰·안읽음 뱃지·최근 활동순 정렬. 새 메시지가 방을 맨 위로 올리고, 멤버십 이벤트는 디바운스 reload. 액션: `markRead`, `hideRoom`, `unhideRoom`. |
+| `useMemberList(roomId)` | 라이브 멤버 목록 — 역할, `operators`, `activeMemberIds`(읽음 카운트 계산용), presence 점은 in-place 갱신. |
+| `useRoomFiles(roomId, opts?)` | 파일함·앨범 페이지네이션(최신순): `items`, `media`(이미지/영상만), `hasMore`, `store.loadMore()` / `store.refresh()`. |
+| `useRoomSettings(roomId)` | 방 설정 액션: `setMuted` / `setPushTrigger`, 초대 링크 CRUD, 참여 요청 수신함(승인/거절), `leave` / `clearHistory` / `deleteMyMessages`, 오퍼레이터 모더레이션(`freeze`, `setPublic`, `muteMember` 등). |
+| `ChatMessage` | 히스토리(REST)·라이브(WS)·낙관적 메시지를 하나로 통일한 뷰모델. |
+| `RoomStore` | `useMessages` 뒤의 프레임워크 무관 store. 훅 밖에서도 사용 가능 (테스트, 비-React 글루). |
+
+`@noverachat/sdk-web`의 모든 export를 재노출하므로 `NoveraChat`, `Room`, 메시지/이벤트 타입 등을 한 번의 import로 쓸 수 있다.
+
+## 문서
+
+React 특유의 가이드는 [NoveraChat 문서 사이트](https://dev-chat-docs.novera.town/ko/react/getting-started/build-a-chat-screen)에 발행된다 (원본은 `docs/`) — [채팅 화면 만들기](https://dev-chat-docs.novera.town/ko/react/getting-started/build-a-chat-screen)부터.
+
+| 섹션 | 내용 |
+|---|---|
+| [시작하기](https://dev-chat-docs.novera.town/ko/react/getting-started/build-a-chat-screen) | 설치 + 채팅 화면 조립 |
+| [가이드](https://dev-chat-docs.novera.town/ko/react/guides/state-and-lifecycle) | 상태와 라이프사이클 · 채팅방 리스트 · 읽음 표시 · 파일과 미디어 · 방 설정 화면 |
+| [레퍼런스](https://dev-chat-docs.novera.town/ko/react/reference/hooks) | 훅·store API |
+
+채팅 **동작**(인증·연결·메시징·룸·푸시·에러)은 [`@noverachat/sdk-web`](../sdk-web/README.ko.md)에 문서화돼 있고, 여기서 중복하지 않는다.
+
+## 참고
+
+- 읽음 워터마크(`markRead`)는 코어 SDK 안에서 디바운스된다. store가 탭 숨김/닫힘과 언마운트 시 자동으로 flush하므로 안읽음 카운트가 기기 간에 정확하게 유지된다.
+- StrictMode 안전: 시뮬레이션된 이중 마운트에서 구독이 깨끗하게 attach/detach되고, 초기 히스토리 로드는 중복 가드가 있다.

package/README.md

@@ -0,0 +1,99 @@
+# @noverachat/sdk-react
+
+> 🇰🇷 [한국어](./README.ko.md)
+
+React hooks/bindings for NoveraChat — a thin layer over [`@noverachat/sdk-web`](../sdk-web) (the headless `NoveraChat` / `Room` core). It does NOT reimplement chat logic and it does NOT ship chat UI — this package is only the glue: a lifecycle-managed provider and hooks that turn the SDK's events into React state.
+
+## Install
+
+```sh
+npm i @noverachat/sdk-react @noverachat/sdk-web react
+```
+
+`react >= 18` is a peer dependency (uses `useSyncExternalStore`).
+
+## Quick start
+
+```tsx
+import {
+  NoveraChatProvider,
+  useMessages,
+  useTyping,
+} from "@noverachat/sdk-react";
+
+function App() {
+  return (
+    <NoveraChatProvider
+      options={{
+        appId: "app_9f8k2x",
+        endpoint: "https://chat.example.com",
+        tokenProvider: async () => fetchJwt(),
+      }}
+    >
+      <ChatScreen roomId="room_123" />
+    </NoveraChatProvider>
+  );
+}
+
+function ChatScreen({ roomId }: { roomId: string }) {
+  const { messages, hasMore, store } = useMessages(roomId);
+  const { isAnyoneTyping, setTyping } = useTyping(roomId);
+
+  return (
+    <>
+      {hasMore && <button onClick={() => store.loadMore()}>older…</button>}
+      {messages.map((m) => (
+        <div key={m.id}>
+          {m.isDeleted ? "(deleted)" : m.content}
+          {m.status === "sending" && " ⏳"}
+          {m.status === "failed" && " ⚠️"}
+        </div>
+      ))}
+      {isAnyoneTyping && <span>typing…</span>}
+      <input
+        onChange={() => setTyping(true)}
+        onKeyDown={(e) => {
+          if (e.key !== "Enter") return;
+          store.send(e.currentTarget.value);
+          e.currentTarget.value = "";
+        }}
+      />
+    </>
+  );
+}
+```
+
+## API
+
+| Export | What it is |
+|---|---|
+| `NoveraChatProvider` / `useNoveraChat()` | Creates a `NoveraChat`, runs `connect()`/`disconnect()` over the mount lifecycle; the hook reads it anywhere below. Options are read **once** — remount with a new `key` to reconnect differently. |
+| `useRoom(roomId)` | The `Room` facade, for direct SDK calls the hooks don't cover (members, announcements, invites, moderation, …). |
+| `useMessages(roomId, opts?)` | Live message list (`ChatMessage[]`, oldest first) + `hasMore` + `readWatermarks`, plus the backing `RoomStore` for actions: `send`, `sendFile` (with upload progress), `edit`, `delete`, `toggleReaction`, `markRead`, `loadMore`, `search`, `isReadBy`, `readCount`. Sends are optimistic — a `sending` bubble flips to `sent` on ack or `failed` on error. |
+| `useTyping(roomId, opts?)` | Who's typing (auto-expires after `timeoutMs`, default 5s) + `setTyping` to broadcast your own state. |
+| `useUnread(opts?)` | Account-wide unread badge: `total`, per-room `summary`, `refresh()`, optional `refreshIntervalMs` polling. |
+| `useRoomList(opts?)` | Live chat-room list (채팅 탭): previews, unread badges, most-recent-first ordering. New messages bump rooms to the top; membership events trigger a debounced reload. Actions: `markRead`, `hideRoom`, `unhideRoom`. |
+| `useMemberList(roomId)` | Live member list — roles, `operators`, `activeMemberIds` (for read-receipt math), presence dots updated in place. |
+| `useRoomFiles(roomId, opts?)` | Paginated media/file grid (파일함·앨범), newest first: `items`, `media` (images/videos only), `hasMore`, `store.loadMore()` / `store.refresh()`. |
+| `useRoomSettings(roomId)` | Room-settings actions: `setMuted` / `setPushTrigger`, invite-link CRUD, join-request inbox (approve/reject), `leave` / `clearHistory` / `deleteMyMessages`, operator moderation (`freeze`, `setPublic`, `muteMember`, …). |
+| `ChatMessage` | Uniform view model over history (REST), live (WS) and optimistic messages. |
+| `RoomStore` | The framework-agnostic store behind `useMessages`, usable outside hooks (tests, non-React glue). |
+
+Everything from `@noverachat/sdk-web` is re-exported, so a single import gets you `NoveraChat`, `Room`, message/event types, etc.
+
+## Documentation
+
+React-specific guides are on the [NoveraChat docs site](https://dev-chat-docs.novera.town/react/getting-started/build-a-chat-screen) (source under `docs/`) — start with [build a chat screen](https://dev-chat-docs.novera.town/react/getting-started/build-a-chat-screen).
+
+| Section | Contents |
+|---|---|
+| [Getting started](https://dev-chat-docs.novera.town/react/getting-started/build-a-chat-screen) | Install + wire a chat screen |
+| [Guides](https://dev-chat-docs.novera.town/react/guides/state-and-lifecycle) | State & lifecycle · chat-room list · read receipts · files & media · room settings screen |
+| [Reference](https://dev-chat-docs.novera.town/react/reference/hooks) | Hooks & stores API |
+
+Chat **behavior** — auth, connection, messaging, rooms, push, errors — is documented in [`@noverachat/sdk-web`](../sdk-web/README.md), not duplicated here.
+
+## Notes
+
+- The read watermark (`markRead`) is debounced inside the core SDK; the store flushes it automatically when the tab is hidden/closed and on unmount, so unread counts stay correct across devices.
+- StrictMode-safe: subscriptions attach/detach cleanly across the simulated double mount, and the initial history load is guarded against duplication.