@kispi/chat 0.1.2 → 0.2.1

package/README.en.md

@@ -0,0 +1,404 @@
+# @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_`.
+
+```sh
+npm install @kispi/chat
+```
+
+This document covers **the entire surface**. How to get started is here too.
+
+---
+
+## `@kispi/chat` — client
+
+### `createChatClient(options): ChatClient`
+
+| Option | Type | |
+|---|---|---|
+| `url` | `string` | **Required.** Pass the origin only. The SDK appends `/v1/ws?v=1` |
+| `key` | `string` | **Required.** A `pk_`. It is public, so it is fine to put in the browser |
+| `token` | `() => string \| Promise<string>` | **Required.** A user token signed by your backend. Called again on every connect and whenever REST gets a 401, so an expired one is never reused. A throw is retried with backoff; **throwing a `ChatError` means do not retry** (see below) |
+| `restURL` | `string` | REST address. If omitted, it is derived from `url` (`ws://` → `http://`) |
+| `externalToken` | `() => string \| Promise<string>` | External mode. If given, it **takes precedence over `token`** (same order the server checks in). **The server still rejects it, so there is no use for it today** |
+| `WebSocket` | `new (url) => WebSocketLike` | Implementation to use instead of the global. Injected in tests |
+| `fetch` | `typeof fetch` | Same as above |
+
+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`
+
+| Property | |
+|---|---|
+| `state` | `'connecting' \| 'open' \| 'reconnecting' \| 'closed'` |
+| `user` | The connected user. `{id, name, avatar?}` |
+| `connectionId` | Identifier used for support requests and forced disconnects |
+| `hello` | Everything the server sent on connect (limits, total unread, warnings) |
+
+| Method | |
+|---|---|
+| `connect()` | Connects. If already connected or connecting, it joins that attempt. Rejects on failure, but **retries continue in the background** (see below) |
+| `close()` | Disconnects. This one does not reconnect. Call `connect()` to come back |
+| `room(roomId)` | Room handle. Same id, same object |
+| `roomByKey(key)` | Handle for a room opened by key. The server tells you the id when you subscribe. **Does not create the room** — for a key that doesn't exist, `subscribe()` rejects with `not_found` (see below) |
+| `rooms.list({cursor?, limit?})` | Rooms I'm a member of + unread + last message |
+| `rooms.discover({type?, cursor?, limit?})` | Browse public rooms |
+| `rooms.members(roomId).list/add/remove` | Member management |
+| `unread()` | Total and per-room breakdown |
+| `updateMe(meta)` | My `meta`. **`name` and `avatar` come from the token claims** |
+| `send(type, data?, timeoutMs?)` | Raw frame. Only for calling things not on the surface |
+
+| Event | |
+|---|---|
+| `state` | The four values above |
+| `error` | The client stopped at `closed` on its own, and why (a `ChatError`): an authentication refusal, or a `ChatError` from `token()`. Not emitted for `close()` |
+| `notification` | A new message arrived in a room I'm a member of, but I'm not viewing that room |
+| `user.presence` | Presence changes of my other connections |
+| `frame` | Every received frame. For debugging |
+
+`on` returns an unsubscribe function.
+
+```ts
+const off = chat.on('state', s => setStatus(s))
+off()
+```
+
+### `Room`
+
+| Property | |
+|---|---|
+| `messages` | Ascending by seq. **The SDK handles ordering and gap filling.** A new array on every change |
+| `id` / `key` | Room identifiers. If opened by key, `id` is absent until you subscribe |
+| `lastSeq` | The room's last seq as reported by the server |
+| `presence` | `{count, users?, capped?}` |
+
+| Method | |
+|---|---|
+| `subscribe()` | Turns on the live feed and reads the latest 100. Does nothing if already caught up. **Fine to call before connecting** — it waits until connected (rejects with `closed` on `close()`) |
+| `unsubscribe()` | Stops viewing this room. It is not resubscribed on reconnect |
+| `send({text, attachments?, entities?, replyTo?, threadId?, meta?}, {clientMessageId?})` | Publish. Acked with `{messageId, seq}`. If a subscription is in progress, it waits for it |
+| `loadOlder({limit?})` | Reads the page before the oldest message (default 100) and **prepends it to `messages`.** Returns `{messages, hasMore}`. Use it when scrolling up. If the list is empty (before subscribing), it reads nothing |
+| `history({before?, after?, limit?, view?})` | Reads the past directly. **Independent of `messages`.** `view` is `'main'`, `'all'`, or `{thread: id}` |
+| `reload()` | Re-reads the latest page |
+| `react(messageId, emoji)` / `unreact(...)` | Reactions. Idempotent |
+| `reactionsOf(messageId, {emoji?, cursor?, limit?})` | Who reacted. **Each row is a (user, emoji) pair**, so one person can appear on several rows. `limit` defaults to 50, max 100; the last page's `cursor` is an empty string |
+| `markRead(seq, {threadId?})` | Read cursor |
+| `typing()` | Typing indicator. Does not throw |
+| `join()` / `leave()` | Membership |
+| `presenceList()` | Who is in this room right now |
+| `resume()` | Resubscribes after reconnecting. The SDK calls it for you |
+
+Event names are **exactly the wire names**. `message.created`, `message.updated`,
+`message.deleted`, `reaction.added`, `reaction.removed`, `thread.updated`,
+`presence`, `typing`, `read`, `member.joined`, `member.left`, `room.updated`,
+`room.deleted`, `custom`.
+
+The SDK emits three more that have no wire counterpart.
+
+| Event | When |
+|---|---|
+| `messages` | Every time the list changes. **A new array each time; an emitted array is never touched again** |
+| `error` | Reading history or filling a gap failed. **The room resubscribes itself** (from 1 s, doubling, 5 tries while connected, again on every reconnect). The retry button for a person is `subscribe()` |
+| `reset` | The cursor was older than the retention period, so the list was discarded and refilled. **You must discard what you rendered** |
+
+### Things to know
+
+**`messages` changes reference.** Every time the list changes a new array comes out, and
+an array once emitted, along with the row objects in it, is never modified afterward. So you
+can put it straight into state that compares by reference. Rows follow the same rule: only a
+row an event changed (edit, delete, reaction, thread) is a new object, and the others keep
+their reference — **same reference means unchanged**, so row-level memoization is safe. The
+converse is not promised: `reload()` and reconnect catch-up fetch rows from the server again,
+so a different reference can carry the same content.
+
+```ts
+// 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))
+```
+
+Wrapping it in `$state` (a deep proxy) or `ref` works, but does unnecessary work. 0.1.x
+modified the same array in place and emitted it again, so on the reference-comparing side
+the screen froze.
+
+**Attach the past to the same list with `loadOlder()`.** `history()` is a direct read that
+doesn't touch the list, so merging its results with the live list, filtering duplicates, and
+handling `reset` and reconnects all fall to the consumer. `loadOlder()` puts those rows into
+`messages`, so ordering, deduplication, deletion, reactions, and reconnects apply to them just
+like any other row. Calling it several times concurrently still makes one request, and if
+`hasMore` is `false` you're at the start of the room (or of the retention period).
+`reset` or `reload()` discards the attached past as well.
+
+```ts
+const { hasMore } = await room.loadOlder()
+```
+
+**It's safe to send once `await room.subscribe()` has finished.** That said, you may
+`send` without waiting — if a subscription is in progress, `send` (and `react`, `markRead`,
+`loadOlder`, etc.) waits for it before going out. If the subscription fails, it rejects with
+that error. A `roomByKey` room that was never subscribed doesn't know its id, so it rejects
+immediately with `closed`. Publishing while `chat.state` is `reconnecting` also rejects with
+`closed` — the SDK does not queue things to send.
+
+**Opening by key does not create a room.** `roomByKey(key).subscribe()` only looks up an
+existing room, and if there is none it's `not_found`. Rooms are created by the backend with
+the `sk_` (`rooms.ensure({key, type})` in `@kispi/chat/server` — it's get-or-create, returning
+the room as-is if it exists, so it's fine to call on every page load). If you turn on the app
+setting `client_room_create`, user tokens can also call `PUT /v1/rooms` (allowed types, key
+pattern, 50-per-day limit), but since the `pk_` is public, that becomes a door through which
+anyone can stamp out rooms. It is off by default, and we recommend keeping it off.
+
+**The connection comes back on its own.** If the socket drops or `token()` throws, it
+reconnects with exponential backoff (0.5 s up to 30 s, with jitter). **The first `connect()`
+is the same** — on failure the `await` rejects so the caller knows, and retries continue in
+the background (`state` is `reconnecting`, then `open` once it connects). The server's
+connection limit (`rate_limited`) and server failures (`internal`) take the same path (a
+limit waits as long as the server says). So there's no need to write your own retry loop.
+
+**Subscribe rooms first; don't wait for the connection.** `subscribe()` waits until the
+client is connected and then goes out, so even if the first `connect()` fails, the room fills
+the moment a background retry connects. Putting `subscribe()` after `await chat.connect()`
+means a rejected connect never reaches the subscribe line.
+
+```ts
+const room = chat.roomByKey('lobby')
+room.on('messages', render)
+chat.connect().catch(showOffline) // retries continue even on failure
+await room.subscribe()            // settles once connected
+```
+
+Three things stop it: `close()`, the server refusing authentication (`unauthorized`,
+`forbidden` — repeating the same token would just be hammering the server), and **`token()`
+throwing a `ChatError`**. That is how you say a failure is not worth retrying, like a ban or
+an ended session:
+
+```ts
+token: async () => {
+  const res = await fetch('/api/chat-token')
+  if (res.status === 403) throw new ChatError('forbidden', 'banned') // not retried
+  if (!res.ok) throw new Error(`token ${res.status}`)                // retried with backoff
+  return (await res.json()).token
+}
+```
+
+The last two leave `state` at `closed` and report why on `chat.on('error')` — even mid-reconnect
+or during a REST token refresh, where there is no caller to reject. Call `connect()` to come
+back.
+
+**The SDK handles token expiry.** The socket authenticates only once on connect, so it stays
+fine even when the token expires, but REST checks the token on every request. When REST gets a
+401, the SDK calls `token()` again and retries **once**. A second 401 (origin, revoked token,
+ban) is thrown as-is. There's no need to reconnect periodically.
+
+The SDK neither caches the token nor hands it out. Cache inside `token()` (there's no need to
+hit your backend on every call). **Don't reuse this token as the credential for your own
+backend's API** — it is made to be presented to the chat engine, and mixing the two turns a
+token leaked on one side into a key for the other. Use your own session for your own API.
+
+**The SDK handles ordering and gap filling.** If frames arrive out of order or a reconnect
+misses a range, it fills them in via REST. Gaps larger than one page (100) are filled
+completely too.
+
+**Reconnecting only recovers messages.** Because the history route covers messages only,
+reactions on **older messages** or room renames that happened while disconnected are not
+reflected. In that case, `await room.reload()`.
+
+**`typing` is also delivered to the sender.** If you render "X is typing", skip your own
+`userId`.
+
+**Don't ignore `reset`.** If you keep appending to the old list, you're left with a gap that
+nobody fills.
+
+### 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 need to touch nginx or any other proxy.
+
+```sh
+chat-server app create my-app --origins https://example.com
+chat-server key create <app-id> pk --origins https://staging.example.com
+```
+
+Scheme, host, and port must match **exactly**. `https://example.com` and
+`https://www.example.com` are different origins, and so are `http://localhost:3000` and
+`http://127.0.0.1:3000`. Add development origins separately.
+
+**In Node it works without this setting.** WHATWG `fetch` and `WebSocket` don't send
+`Origin` outside the browser, and the engine lets requests without an `Origin` through. That's
+how code that's green in Node can return 401 only in the browser — this section is the reason.
+
+If the origin isn't on the list, REST rejects with 401, and the message states the cause:
+
+```
+origin not allowed for this publishable key: add it to the key's allowed_origins
+```
+
+**If it looks like the socket works but REST doesn't, look here.** WebSocket isn't subject to
+CORS, so connecting and live messages run fine, while history, unread, and reconnect gap
+filling are REST and fail silently. The symptom shows up as "messages arrive, but scrolling up
+shows nothing".
+
+### Errors
+
+Failures are `ChatError`.
+
+```ts
+try {
+  await room.send({ text })
+} catch (err) {
+  if (err instanceof ChatError && err.code === 'rate_limited') {
+    retryAfter(err.retryAfterMs)
+  }
+}
+```
+
+| Field | |
+|---|---|
+| `code` | `unauthorized`, `rate_limited`, `not_found`, `invalid`, `timeout`, `closed`, ... |
+| `retryAfterMs` | Wait time reported by the server when you hit a limit |
+| `appCode` | Consumer-side code attached by a `before_publish` webhook when rejecting |
+| `status` | HTTP status, if the error came from a REST call |
+
+---
+
+## `@kispi/chat/server` — backend
+
+Uses the `sk_`. **Never put it in the browser.**
+
+```ts
+import { createChatServer } from '@kispi/chat/server'
+
+const chat = createChatServer({
+  url: 'https://chat.example.com',
+  secretKey: process.env.CHAT_SECRET_KEY!,
+  keyId: process.env.CHAT_KEY_ID!,
+  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.
+
+| Field | |
+|---|---|
+| `userId` | **Required.** Becomes the JWT `sub`. Your service's user id |
+| `name` | **Required.** This value wins on every connect |
+| `avatar`, `meta` | Optional |
+| `ttlSeconds` | Default 1 hour, max 24 hours. Exceeding it is rejected, not truncated |
+
+### `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.
+
+```ts
+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.** A guest id is not a secret — it
+goes out as `sender.id` on every message in the room. A token endpoint that "re-signs the id
+the browser kept" gives that guest's identity to anyone who copied the id from someone's
+message. A format check (`g_` + UUID regex) doesn't prevent this. A UUID being hard to guess
+means nothing once the value is public.
+
+`guest()` has the browser hold a **credential** instead of the id. It is
+`g1.<userId>.<MAC>`, with the MAC made from `guestSecret`. If the returned credential
+verifies, it signs with the id inside it; if it's missing or invalid, it signs a new guest
+(`g_` + 22 random characters, `created: true`). Where possible, keep it in an `httpOnly`
+cookie so page scripts can't read it.
+
+| | |
+|---|---|
+| `guestSecret` | At least 32 characters. Keep it on the backend only. **Don't derive it from the `sk_`** — the `sk_` is a key you rotate if it leaks, and rotating it must not turn every guest into a new person |
+| Rotation | Pass an array: `[new, old]`. Signs with the first and verifies with all. A credential verified with an old one is re-signed with the same `userId` and returned, so it migrates on the next visit |
+| Leak | If the secret leaks, anyone can become any guest. **Removing** the old one from the list turns every guest into a new person — losing identity is better than impersonation |
+
+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
+
+| Group | Methods |
+|---|---|
+| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `members.list/add/remove` |
+| `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list`, `delete` |
+| `users` | `list({cursor?, limit?})`, `update`, `delete({purgeMessages?})`, `ban({until, reason?})`, `unban`, `revokeTokens`, `disconnect` |
+| `events` | `list({after?, limit?})` — the outbox. Catches up on missed webhooks |
+| `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` |
+
+`users.ban`'s `until` is **unix milliseconds and required.** For an indefinite ban, pick a
+far-future time yourself — it goes into the audit log as a decision, not an accident.
+
+`users.*` works only **after the person has connected at least once**. Users come into
+existence by connecting.
+
+`users.list` is for the console. Reverse uid order, `limit` defaults to 50, max 100, `cursor`
+is an opaque string and an empty string marks the last page. **Deleted users are included too,
+and `deletedAt` marks them** — filter on it if you only want live users. This is the opposite of
+the in-room lists (members, reactions, reads) hiding deleted users' ids, because those are lists
+read by **other users**, whereas this one requires the `sk_`, so the reader is the very backend
+that issued those ids.
+
+`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 anyone not connected at that moment never learns of it — for a signal that must be
+received even after reconnecting, use `messages.send(roomId, {kind:'system', ...})`.
+
+### Webhooks
+
+```ts
+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.** The MAC is over the bytes the server sent, and something parsed
+and re-serialized is a different string.
+
+**The signature covers the headers too.** The canonical string is
+`` `${t}\n${event}\n${delivery}\n${rawBody}` `` and the order is fixed. So
+`verify` reads `X-Chat-Event` and `X-Chat-Delivery` **before verifying**, and a replay with only
+the headers swapped won't pass — `X-Chat-Delivery` is the deduplication key, so if it were
+outside the signature, a single captured delivery could be counted as any number of new events.
+
+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.
+
+---
+
+## Development
+
+```sh
+pnpm install
+pnpm build          # ESM + CJS + type declarations
+pnpm exec vitest run
+pnpm exec tsc --noEmit
+```
+
+Tests use **injection**, not mocks. Swapping in `WebSocket` and `fetch` means there's no need to
+imitate the server, and the integration-style files connect to a **live server** outright.
+Running them requires Postgres and Redis.

package/README.md

@@ -22,7 +22,7 @@ npm install @kispi/chat
 |---|---|---|
 | `url` | `string` | **필수.** 오리진만 준다. SDK가 `/v1/ws?v=1`을 붙인다 |
 | `key` | `string` | **필수.** `pk_`. 공개값이라 브라우저에 넣어도 된다 |
-| `token` | `() => string \| Promise<string>` | **필수.** 백엔드가 서명한 유저 토큰. 접속할 때마다 다시 부르므로 만료된 것이 재사용되지 않는다 |
+| `token` | `() => string \| Promise<string>` | **필수.** 백엔드가 서명한 유저 토큰. 접속할 때마다, 그리고 REST가 401을 받을 때 다시 부르므로 만료된 것이 재사용되지 않는다. 던지면 백오프로 다시 부르고, **`ChatError`를 던지면 다시 부르지 않는다**(아래) |
 | `restURL` | `string` | REST 주소. 생략하면 `url`에서 유도한다(`ws://` → `http://`) |
 | `externalToken` | `() => string \| Promise<string>` | external 모드. 주면 **`token`보다 우선한다**(서버의 판정 순서와 같다). **서버가 아직 거절하므로 오늘은 쓸 곳이 없다** |
 | `WebSocket` | `new (url) => WebSocketLike` | 전역 대신 쓸 구현. 테스트에서 주입한다 |
@@ -42,10 +42,10 @@ npm install @kispi/chat
 
 | 메서드 | |
 |---|---|
-| `connect()` | 붙는다. 이미 붙어 있거나 붙는 중이면 그 시도에 합류한다 |
-| `close()` | 끊는다. 이건 재접속하지 않는다 |
+| `connect()` | 붙는다. 이미 붙어 있거나 붙는 중이면 그 시도에 합류한다. 실패하면 거절하지만 **재시도는 백그라운드에서 계속된다**(아래) |
+| `close()` | 끊는다. 이건 재접속하지 않는다. 다시 붙으려면 `connect()` |
 | `room(roomId)` | 방 핸들. 같은 id면 같은 객체 |
-| `roomByKey(key)` | 키로 여는 방 핸들. 구독할 때 서버가 id를 알려 준다 |
+| `roomByKey(key)` | 키로 여는 방 핸들. 구독할 때 서버가 id를 알려 준다. **방을 만들지 않는다** — 없는 키면 `subscribe()`가 `not_found`로 거절한다(아래) |
 | `rooms.list({cursor?, limit?})` | 내가 멤버인 방 + unread + 마지막 메시지 |
 | `rooms.discover({type?, cursor?, limit?})` | 공개 방 탐색 |
 | `rooms.members(roomId).list/add/remove` | 멤버 관리 |
@@ -56,6 +56,7 @@ npm install @kispi/chat
 | 이벤트 | |
 |---|---|
 | `state` | 위 네 값 |
+| `error` | 클라이언트가 스스로 `closed`로 멈췄고 그 이유(`ChatError`). 인증 거절이나 `token()`의 `ChatError`. `close()`로 닫을 때는 없다 |
 | `notification` | 멤버인 방에 새 메시지가 왔는데 그 방을 보고 있지 않을 때 |
 | `user.presence` | 내 다른 접속의 presence 변화 |
 | `frame` | 받은 프레임 전부. 디버깅용 |
@@ -71,17 +72,18 @@ off()
 
 | 프로퍼티 | |
 |---|---|
-| `messages` | seq 오름차순. **정렬과 구멍 메우기는 SDK가 한다** |
+| `messages` | seq 오름차순. **정렬과 구멍 메우기는 SDK가 한다.** 바뀔 때마다 새 배열이다 |
 | `id` / `key` | 방 식별자. 키로 열었으면 구독 전까지 `id`가 없다 |
 | `lastSeq` | 서버가 알려 준 방의 마지막 seq |
 | `presence` | `{count, users?, capped?}` |
 
 | 메서드 | |
 |---|---|
-| `subscribe()` | 라이브 피드를 켜고 최근 100건을 읽는다. 이미 따라잡혔으면 아무것도 안 한다 |
+| `subscribe()` | 라이브 피드를 켜고 최근 100건을 읽는다. 이미 따라잡혔으면 아무것도 안 한다. **연결 전에 불러도 된다** — 붙을 때까지 기다린다(`close()`면 `closed`로 거절) |
 | `unsubscribe()` | 이 방 보기를 그만둔다. 재접속해도 다시 구독하지 않는다 |
-| `send({text, attachments?, entities?, replyTo?, threadId?, meta?}, {clientMessageId?})` | 발행. ack로 `{messageId, seq}` |
-| `history({before?, after?, limit?, view?})` | 과거를 직접 읽는다. `view`는 `'main'`, `'all'`, `{thread: id}` |
+| `send({text, attachments?, entities?, replyTo?, threadId?, meta?}, {clientMessageId?})` | 발행. ack로 `{messageId, seq}`. 구독이 진행 중이면 그것을 기다린다 |
+| `loadOlder({limit?})` | 가장 오래된 메시지 앞 페이지(기본 100)를 읽어 **`messages` 앞에 붙인다.** `{messages, hasMore}`. 스크롤을 올릴 때 쓴다. 목록이 비어 있으면(구독 전) 아무것도 읽지 않는다 |
+| `history({before?, after?, limit?, view?})` | 과거를 직접 읽는다. **`messages`와 따로 논다.** `view`는 `'main'`, `'all'`, `{thread: id}` |
 | `reload()` | 최근 페이지를 다시 읽는다 |
 | `react(messageId, emoji)` / `unreact(...)` | 리액션. 멱등 |
 | `reactionsOf(messageId, {emoji?, cursor?, limit?})` | 누가 눌렀는지. **한 행은 (유저, 이모지) 쌍**이라 한 사람이 여러 줄일 수 있다. `limit` 기본 50 최대 100, 마지막 페이지의 `cursor`는 빈 문자열 |
@@ -100,11 +102,104 @@ off()
 
 | 이벤트 | 언제 |
 |---|---|
-| `messages` | 목록이 바뀔 때마다. 통째로 다시 그리는 UI에 편하다 |
-| `error` | 히스토리를 읽거나 구멍을 메우는 데 실패했다. **다시 시도할 것은 `subscribe()`** |
+| `messages` | 목록이 바뀔 때마다. **매번 새 배열이고, 내보낸 배열은 다시 건드리지 않는다** |
+| `error` | 히스토리를 읽거나 구멍을 메우는 데 실패했다. **방이 스스로 다시 구독한다**(1초부터 두 배씩, 연결된 동안 5번, 재접속마다 다시). 사람이 누를 재시도 버튼은 `subscribe()` |
 | `reset` | 커서가 보존 기간보다 오래돼 목록을 버리고 다시 채웠다. **렌더한 것을 버려야 한다** |
 
-### 알아 둘 것 넷
+### 알아 둘 것
+
+**`messages`는 참조가 바뀐다.** 목록이 바뀔 때마다 새 배열이 나오고, 한 번 내보낸
+배열과 그 안의 행 객체는 이후에 고쳐지지 않는다. 그래서 참조로 비교하는 상태에 그대로
+넣으면 된다. 행도 마찬가지로, 이벤트(수정, 삭제, 리액션, 스레드)가 바꾼 행만 새 객체이고
+나머지 행은 참조가 그대로다 — **참조가 같으면 바뀌지 않은 것**이니 행 단위 memo에 써도
+된다. 반대는 약속하지 않는다: `reload()`와 재접속 따라잡기는 같은 내용의 행을 서버에서
+새로 받아 오므로, 참조가 달라도 내용은 같을 수 있다.
+
+```ts
+// 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))
+```
+
+`$state`(깊은 프록시)나 `ref`로 감싸도 동작하지만 필요 없는 일을 한다. 0.1.x는 같은
+배열을 제자리에서 고쳐 다시 내보내서, 참조로 비교하는 쪽에서는 화면이 멈췄다.
+
+**과거는 `loadOlder()`로 같은 목록에 붙인다.** `history()`는 목록을 건드리지 않는
+직접 읽기라, 그 결과를 라이브 목록과 합치고 중복을 거르고 `reset`과 재접속을
+처리하는 일이 전부 소비자 몫이 된다. `loadOlder()`는 그 행들을 `messages`에 넣으므로
+정렬·중복 제거·삭제·리액션·재접속이 다른 행과 똑같이 적용된다. 동시에 여러 번
+불러도 요청은 하나이고, `hasMore`가 `false`면 방(또는 보존 기간)의 맨 앞이다.
+`reset`이나 `reload()`는 붙인 과거도 함께 버린다.
+
+```ts
+const { hasMore } = await room.loadOlder()
+```
+
+**보내도 되는 때는 `await room.subscribe()`가 끝난 때다.** 다만 기다리지 않고
+`send`해도 된다 — 구독이 진행 중이면 `send`(와 `react`, `markRead`, `loadOlder` 등)가
+그것을 기다렸다가 나간다. 구독이 실패하면 그 에러로 거절한다. 구독한 적도 없는
+`roomByKey` 방은 id를 모르므로 곧바로 `closed`로 거절한다. `chat.state`가
+`reconnecting`인 동안의 발행도 `closed`로 거절한다 — SDK는 보낼 것을 쌓아 두지 않는다.
+
+**키로 연다고 방이 생기지 않는다.** `roomByKey(key).subscribe()`는 있는 방을 찾기만
+하고, 없으면 `not_found`다. 방은 백엔드가 `sk_`로 만든다
+(`@kispi/chat/server`의 `rooms.ensure({key, type})` — 있으면 그대로 돌려주는
+get-or-create라 페이지를 열 때마다 불러도 된다). 앱 설정 `client_room_create`를 켜면
+유저 토큰으로도 `PUT /v1/rooms`를 부를 수 있지만(허용 타입·키 패턴·하루 50개
+한도), `pk_`는 공개값이라 누구나 방을 찍어낼 수 있는 문이 된다. 기본은 꺼져 있고,
+끄는 쪽을 권한다.
+
+**연결은 알아서 돌아온다.** 소켓이 끊기거나 `token()`이 던지면 지수 백오프(0.5초에서
+30초까지, 지터)로 다시 붙는다. **첫 `connect()`도 같다** — 실패하면 `await`는 거절해서
+호출자가 알게 하고, 재시도는 백그라운드에서 이어진다(`state`가 `reconnecting`, 붙으면
+`open`). 서버의 접속 한도(`rate_limited`)와 서버 장애(`internal`)도 같은 길로 다시
+붙는다(한도는 서버가 말한 만큼 기다린다). 그래서 재시도 루프를 직접 짤 필요가 없다.
+
+방은 **연결을 기다리지 말고 먼저 구독해 둔다.** `subscribe()`는 붙을 때까지 기다렸다가
+나가므로, 첫 `connect()`가 실패해도 백그라운드 재시도가 붙는 순간 방이 채워진다.
+`await chat.connect()` 뒤에 `subscribe()`를 두면 connect가 거절될 때 구독 줄에 닿지
+않는다.
+
+```ts
+const room = chat.roomByKey('lobby')
+room.on('messages', render)
+chat.connect().catch(showOffline) // 실패해도 재시도는 계속된다
+await room.subscribe()            // 붙은 뒤 끝난다
+```
+
+멈추는 것은 셋이다. `close()`, 서버의 인증 거절(`unauthorized`, `forbidden` — 같은
+토큰을 반복하는 것은 서버를 두드리는 일이다), 그리고 **`token()`이 `ChatError`를 던질
+때**다. 밴이나 끝난 세션처럼 다시 해도 소용없는 실패는 그렇게 알린다:
+
+```ts
+token: async () => {
+  const res = await fetch('/api/chat-token')
+  if (res.status === 403) throw new ChatError('forbidden', 'banned') // 다시 하지 않는다
+  if (!res.ok) throw new Error(`token ${res.status}`)                // 백오프로 다시 한다
+  return (await res.json()).token
+}
+```
+
+뒤의 둘은 `state`를 `closed`로 두고 `chat.on('error')`로 이유를 낸다. 재접속 중이나
+REST의 토큰 갱신 중이라 거절을 받을 호출자가 없어도 그렇다. 다시 붙으려면 `connect()`.
+
+**토큰 만료는 SDK가 처리한다.** 소켓은 접속할 때 한 번만 인증하므로 토큰이 만료돼도
+멀쩡하지만, REST는 요청마다 토큰을 본다. REST가 401을 받으면 SDK가 `token()`을 다시
+불러 **한 번** 재시도한다. 두 번째 401(오리진, 폐기된 토큰, 밴)은 그대로 던진다.
+주기적으로 재접속할 필요가 없다.
+
+SDK는 토큰을 캐시하지도, 꺼내 주지도 않는다. 캐시는 `token()` 안에서 한다(부를
+때마다 백엔드를 칠 필요는 없다). **이 토큰을 자기 백엔드 API의 인증으로 다시 쓰지
+않는다** — 채팅 엔진에 내라고 만든 것이고, 둘을 섞으면 한쪽에 새어 나간 토큰이 다른
+쪽의 열쇠가 된다. 자기 API에는 자기 세션을 쓴다.
 
 **정렬과 구멍 메우기는 SDK가 한다.** 프레임이 순서 없이 오거나 재접속으로 구간을
 놓치면 REST로 채운다. 한 페이지(100)를 넘는 구멍도 전부 채운다.
@@ -167,6 +262,7 @@ try {
 | `code` | `unauthorized`, `rate_limited`, `not_found`, `invalid`, `timeout`, `closed`, ... |
 | `retryAfterMs` | 한도에 걸렸을 때 서버가 알려 준 대기 시간 |
 | `appCode` | `before_publish` 웹훅이 거절하며 붙인 소비자 쪽 코드 |
+| `status` | REST 호출에서 난 에러면 HTTP 상태 |
 
 ---
 
@@ -182,6 +278,7 @@ const chat = createChatServer({
   secretKey: process.env.CHAT_SECRET_KEY!,
   keyId: process.env.CHAT_KEY_ID!,
   webhookSecret: process.env.CHAT_WEBHOOK_SECRET,
+  guestSecret: process.env.CHAT_GUEST_SECRET,   // guest()를 쓸 때만
 })
 ```
 
@@ -196,6 +293,40 @@ const chat = createChatServer({
 | `avatar`, `meta` | 선택 |
 | `ttlSeconds` | 기본 1시간, 최대 24시간. 넘으면 자르지 않고 거절한다 |
 
+### `chat.guest({credential?, name, avatar?, meta?, ttlSeconds?})`
+
+로그인하지 않은 방문자의 신원. `{userId, credential, token, created}`를 돌려준다.
+네트워크도 저장소도 쓰지 않는다.
+
+```ts
+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: '손님' })
+  res.cookie('chat_guest', g.credential, { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 400 * 864e5 })
+  res.json({ token: g.token })
+})
+```
+
+**브라우저가 돌려준 `userId`를 그대로 서명하면 안 된다.** 게스트 id는 비밀이 아니다 —
+방의 모든 메시지에 `sender.id`로 실려 나간다. "브라우저가 보관한 id를 다시 서명"하는
+토큰 엔드포인트는 남의 메시지에서 id를 복사한 누구에게나 그 게스트의 신원을 준다.
+형식 검사(`g_` + UUID 정규식)는 이것을 막지 못한다. UUID가 추측하기 어려운 것은
+공개된 값 앞에서는 아무 의미가 없다.
+
+`guest()`는 브라우저가 id 대신 **자격증명**을 들게 한다. `g1.<userId>.<MAC>`이고 MAC은
+`guestSecret`으로 만든다. 돌아온 자격증명이 검증되면 그 안의 id로, 없거나 틀리면
+새 게스트(`g_` + 무작위 22자, `created: true`)로 서명한다. 가능하면 `httpOnly` 쿠키에
+두어 페이지의 스크립트가 읽지 못하게 한다.
+
+| | |
+|---|---|
+| `guestSecret` | 32자 이상. 백엔드에만 둔다. **`sk_`에서 유도하지 않는다** — `sk_`는 유출되면 돌리는 키이고, 돌릴 때 모든 게스트가 새 사람이 되면 안 되기 때문이다 |
+| 교체 | 배열로 준다: `[새것, 옛것]`. 첫 번째로 서명하고 전부로 검증한다. 옛것으로 검증된 자격증명은 같은 `userId`로 새로 서명해 돌려주므로 다음 방문에 옮겨 간다 |
+| 유출 | 비밀이 새면 누구든 아무 게스트가 될 수 있다. 옛것을 목록에서 **빼면** 모든 게스트가 새 사람이 된다 — 신원을 잃는 것이 사칭보다 낫다 |
+
+게스트 id는 `g_`로 시작한다. 로그인 유저의 id가 `g_`로 시작하지 않게 하면 두 공간이
+겹치지 않는다.
+
 ### 나머지
 
 | 그룹 | 메서드 |

package/dist/{chunk-T3QOUFOM.js → chunk-5QQRM7BH.js}

@@ -5,6 +5,8 @@ var ChatError = class extends Error {
   retryAfterMs;
   /** The consumer's own code, when a before_publish hook denied this. */
   appCode;
+  /** The HTTP status, when this came from a REST call. */
+  status;
   constructor(code, message, extra) {
     super(message);
     this.name = "ChatError";