@kispi/chat 0.7.5 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -62,6 +62,7 @@ is in the browser, the whole app is open.
62
62
  | `state` | The four values above |
63
63
  | `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()` |
64
64
  | `notification` | A new message arrived in a room I'm a member of, but I'm not viewing that room |
65
+ | `notification.typing` | `{roomId, userId, threadId?}` — someone is typing in a room I'm a member of but **have not subscribed** (a room list's "typing…"). It comes **only for small rooms** (about ten members or fewer; the engine may change it) — a bigger room sends nothing. Never for my own typing; for a subscribed room use `typists()` / `typing.changed`. Show it for five seconds or more, and clear it when that user's message arrives |
65
66
  | `resumed` | `{reconnected}` — back after a reconnect (`true`), or a tab/app return, network return or back/forward-cache restore (`pageshow`) found the socket alive and resubscribed every room (`false`). Rooms and `roomList()` catch themselves up; use it to refetch **what the SDK does not hold** (an activity feed, search results) |
66
67
  | `user.presence` | Presence changes of my other connections |
67
68
  | `frame` | Every received frame. For debugging |
@@ -185,6 +186,21 @@ room.on('messages', m => (messages.value = m))
185
186
  showTyping(userId, name ?? 'Someone') // clearing it after ~5 seconds is yours to do
186
187
  })
187
188
  ```
189
+ - **Draw a room list's "typing…" from `notification.typing`.** A room you have not subscribed gets no
190
+ `typing`, so this event stands in -- for small rooms only (once you subscribe the room, the same person's
191
+ typing arrives as `typing.changed` and this event stops). There is no "stopped" event: show it for
192
+ **five seconds or more** and clear it when that user's message arrives (`notification`'s `preview.sender.id`).
193
+
194
+ ```ts
195
+ const typingIn = new Map<string, Map<string, number>>() // roomId -> userId -> expiry
196
+ chat.on('notification.typing', ({ roomId, userId, threadId }) => {
197
+ if (threadId !== undefined) return // main timeline only
198
+ const room = typingIn.get(roomId) ?? new Map()
199
+ room.set(userId, Date.now() + 5_000)
200
+ typingIn.set(roomId, room)
201
+ renderRoomRow(roomId) // drop expired entries on a timer or the next render
202
+ })
203
+ ```
188
204
  - **The connection comes back on its own.** It reconnects with exponential backoff, so don't
189
205
  write your own retry loop.
190
206
  - **A reconnect also brings the rows you already hold up to date.** The catch-up (`since`) only fills *new* messages; a reaction, a thread count (`thread.updated`), an edit or a delete on a message you already had rides on no event while you were away. So after a real reconnect (including a tab or app returning from the background, same user) and once the catch-up is done, the SDK **reads the newest 100 messages once (one GET per room) and merges them into the rows it holds.** The list is not replaced (no `reset`, pages loaded with `loadOlder()` stay); each row that actually changed becomes a new object with a `message.updated`, a row that is now deleted becomes a tombstone with `message.deleted` (`messages` fires once). A row that a live event, or a reaction this client pressed, touched while the read was in flight is left alone because that value is newer. **Rows older than the newest 100 are not re-read** — use `reload()` for those. Thread replies live in the same timeline, so they are refreshed along with their roots. If the read fails only `error` is emitted and the room stays subscribed. You do not need to call `reload()` yourself.
package/README.md CHANGED
@@ -62,6 +62,7 @@ npm install @kispi/chat
62
62
  | `state` | 위 네 값 |
63
63
  | `error` | 클라이언트가 스스로 `closed`로 멈췄고 그 이유(`ChatError`). 인증 거절이나 `token()`의 `ChatError`. `close()`로 닫을 때는 없다 |
64
64
  | `notification` | 멤버인 방에 새 메시지가 왔는데 그 방을 보고 있지 않을 때 |
65
+ | `notification.typing` | `{roomId, userId, threadId?}` — 내가 멤버인데 **구독하지 않은 방**에서 누가 입력 중이다(방 목록의 "입력 중…"). **작은 방(멤버 10명 안팎 이하, 엔진이 바꿀 수 있다)에만** 오고 큰 방은 아무것도 안 온다. 내 입력은 안 오고, 구독한 방의 입력은 `typists()`·`typing.changed`로 온다. 5초 이상 보여 주고 그 사람의 글이 오면 지운다 |
65
66
  | `resumed` | `{reconnected}` — 다시 붙었거나(`true`), 탭·앱 복귀·온라인 복귀·bfcache 복원(`pageshow`)에서 소켓이 살아 있어 방들을 다시 구독했다(`false`). 방과 `roomList()`는 스스로 맞추니, **SDK가 들고 있지 않은 것**(활동 피드·검색 결과처럼 앱이 REST로 받은 목록)을 다시 받을 때 쓴다 |
66
67
  | `user.presence` | 내 다른 접속의 presence 변화 |
67
68
  | `frame` | 받은 프레임 전부. 디버깅용 |
@@ -172,6 +173,20 @@ room.on('messages', m => (messages.value = m))
172
173
  showTyping(names) // 빈 배열이면 지운다
173
174
  })
174
175
  ```
176
+ - **방 목록의 "입력 중…"은 `notification.typing`으로 그린다.** 열려 있지 않은(구독하지 않은) 방은 `typing`이 오지 않으니
177
+ 이 이벤트가 대신한다 — 작은 방만(그 방을 구독하면 같은 사람의 입력이 `typing.changed`로 오고 이 이벤트는 안 온다). "멈춤" 이벤트가 없으므로
178
+ 5초 이상 보여 주고, 그 사람의 글이 오면(`notification`의 `preview.sender.id`) 지운다.
179
+
180
+ ```ts
181
+ const typingIn = new Map<string, Map<string, number>>() // roomId -> userId -> 만료 시각
182
+ chat.on('notification.typing', ({ roomId, userId, threadId }) => {
183
+ if (threadId !== undefined) return // 본 타임라인만
184
+ const room = typingIn.get(roomId) ?? new Map()
185
+ room.set(userId, Date.now() + 5_000)
186
+ typingIn.set(roomId, room)
187
+ renderRoomRow(roomId) // 만료는 타이머나 다음 렌더에서 걸러 낸다
188
+ })
189
+ ```
175
190
  - **연결은 알아서 돌아온다.** 끊기면 지수 백오프로 다시 붙으니 재시도 루프를 짜지 않는다.
176
191
  - **재접속하면 이미 들고 있는 행도 최신으로 맞춘다.** 따라잡기(`since`)는 새 메시지만 채우고, 끊긴 사이 이미 있던 메시지에 붙은 리액션·스레드 수(`thread.updated`)·수정·삭제는 어느 이벤트로도 오지 않는다. 그래서 진짜 재접속(탭·앱 복귀의 재구독 포함, 같은 사람일 때) 뒤 따라잡기가 끝나면 SDK가 **가장 최근 100건을 한 번 읽어(방마다 GET 1번) 들고 있는 행에 합친다.** 목록을 바꾸지 않고(`reset` 없음, `loadOlder()`로 불러 둔 윗부분 그대로) 바뀐 행만 새 객체로 `message.updated`, 지워진 행은 tombstone으로 `message.deleted`를 낸다(`messages`는 한 번). 읽는 사이 도착한 라이브 이벤트나 이 클라이언트가 누른 리액션이 더 새 값이라 그 행은 건드리지 않는다. **최근 100건보다 오래된 행은 다시 읽지 않는다** — 필요하면 `reload()`. 스레드 답글은 같은 타임라인이라 루트와 함께 맞춰진다. 이 읽기가 실패하면 `error`만 나가고 방은 구독된 채다. 소비자가 따로 `reload()`를 부를 필요가 없다.
177
192
  - **떠났던 방을 다시 구독할 때도 같다.** 핸들은 캐시되므로 `unsubscribe()` 뒤 `subscribe()`한 방은 들고 있던
package/dist/index.cjs CHANGED
@@ -2535,6 +2535,10 @@ var ChatClient = class extends Emitter {
2535
2535
  this.emit("notification", push?.data);
2536
2536
  return;
2537
2537
  }
2538
+ if (event === "notification.typing") {
2539
+ this.emit("notification.typing", push?.data);
2540
+ return;
2541
+ }
2538
2542
  if (event === "user.presence") {
2539
2543
  this.emit("user.presence", push?.data);
2540
2544
  return;
package/dist/index.d.cts CHANGED
@@ -93,6 +93,18 @@ type UnreadCounts = {
93
93
  /** 총계가 일부만 센 값이다(방이 너무 많아 상한에서 잘렸다). */
94
94
  roomsCapped?: boolean;
95
95
  };
96
+ /**
97
+ * `notification.typing`의 data. 방 `typing`과 같은 뜻에 방 id를 붙인 것이다
98
+ * (유저 채널의 프레임에는 방 봉투가 없다).
99
+ *
100
+ * `userId`는 입력 중인 사람의 외부 id이고, `threadId`는 **루트** id다 —
101
+ * 본 타임라인이면 없다(`typing.changed`의 `threadId`와 같다).
102
+ */
103
+ type NotificationTyping = {
104
+ roomId: string;
105
+ userId: string;
106
+ threadId?: string;
107
+ };
96
108
  type Hello = {
97
109
  connectionId: string;
98
110
  user: AuthUser;
@@ -1025,6 +1037,24 @@ type ChatClientOptions = {
1025
1037
  type ChatClientEvents = {
1026
1038
  state: ConnectionState;
1027
1039
  notification: unknown;
1040
+ /**
1041
+ * Someone is typing in a room you are a member of but have not subscribed,
1042
+ * for a chat list's "typing..." beside that conversation.
1043
+ *
1044
+ * It comes only for small rooms (the engine sends it to rooms of about ten
1045
+ * members or fewer -- a bigger room never gets one, so do not read silence
1046
+ * as "nobody is typing"), never for your own typing, and never for a room
1047
+ * you have subscribed: that room's typing arrives through `room.typists()`
1048
+ * and `typing.changed`, so a screen that shows both reads the open room
1049
+ * from the room and every other row from here.
1050
+ *
1051
+ * There is no "stopped typing" event. Show it for **five seconds or
1052
+ * more** after the last one (the sender's signal comes about every three
1053
+ * seconds) and let it lapse, and clear it when that user's message
1054
+ * arrives -- `notification`'s `preview.sender.id`, or the room's
1055
+ * `message.created`. Not replayed after a reconnect.
1056
+ */
1057
+ 'notification.typing': NotificationTyping;
1028
1058
  'user.presence': unknown;
1029
1059
  /**
1030
1060
  * The client came back: a reconnect reached `hello` again, or `resume()`
@@ -1400,4 +1430,4 @@ declare function buildMentions(text: string, people: readonly {
1400
1430
  */
1401
1431
  declare function mentionSpans(text: string, entities: unknown): MentionSpan[];
1402
1432
 
1403
- export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type EditInput, type Frame, type Hello, type MemberRow, type MentionEntity, type MentionSpan, type Message, type MyRoom, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type RoomInfo, RoomList, type RoomListEvents, type RoomSummary, type SendInput, type SendOptions, Thread, type ThreadEvents, type UnreadCounts, type WebSocketFactory, type WebSocketLike, buildMentions, createChatClient, mentionSpans };
1433
+ export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type EditInput, type Frame, type Hello, type MemberRow, type MentionEntity, type MentionSpan, type Message, type MyRoom, type NotificationTyping, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type RoomInfo, RoomList, type RoomListEvents, type RoomSummary, type SendInput, type SendOptions, Thread, type ThreadEvents, type UnreadCounts, type WebSocketFactory, type WebSocketLike, buildMentions, createChatClient, mentionSpans };
package/dist/index.d.ts CHANGED
@@ -93,6 +93,18 @@ type UnreadCounts = {
93
93
  /** 총계가 일부만 센 값이다(방이 너무 많아 상한에서 잘렸다). */
94
94
  roomsCapped?: boolean;
95
95
  };
96
+ /**
97
+ * `notification.typing`의 data. 방 `typing`과 같은 뜻에 방 id를 붙인 것이다
98
+ * (유저 채널의 프레임에는 방 봉투가 없다).
99
+ *
100
+ * `userId`는 입력 중인 사람의 외부 id이고, `threadId`는 **루트** id다 —
101
+ * 본 타임라인이면 없다(`typing.changed`의 `threadId`와 같다).
102
+ */
103
+ type NotificationTyping = {
104
+ roomId: string;
105
+ userId: string;
106
+ threadId?: string;
107
+ };
96
108
  type Hello = {
97
109
  connectionId: string;
98
110
  user: AuthUser;
@@ -1025,6 +1037,24 @@ type ChatClientOptions = {
1025
1037
  type ChatClientEvents = {
1026
1038
  state: ConnectionState;
1027
1039
  notification: unknown;
1040
+ /**
1041
+ * Someone is typing in a room you are a member of but have not subscribed,
1042
+ * for a chat list's "typing..." beside that conversation.
1043
+ *
1044
+ * It comes only for small rooms (the engine sends it to rooms of about ten
1045
+ * members or fewer -- a bigger room never gets one, so do not read silence
1046
+ * as "nobody is typing"), never for your own typing, and never for a room
1047
+ * you have subscribed: that room's typing arrives through `room.typists()`
1048
+ * and `typing.changed`, so a screen that shows both reads the open room
1049
+ * from the room and every other row from here.
1050
+ *
1051
+ * There is no "stopped typing" event. Show it for **five seconds or
1052
+ * more** after the last one (the sender's signal comes about every three
1053
+ * seconds) and let it lapse, and clear it when that user's message
1054
+ * arrives -- `notification`'s `preview.sender.id`, or the room's
1055
+ * `message.created`. Not replayed after a reconnect.
1056
+ */
1057
+ 'notification.typing': NotificationTyping;
1028
1058
  'user.presence': unknown;
1029
1059
  /**
1030
1060
  * The client came back: a reconnect reached `hello` again, or `resume()`
@@ -1400,4 +1430,4 @@ declare function buildMentions(text: string, people: readonly {
1400
1430
  */
1401
1431
  declare function mentionSpans(text: string, entities: unknown): MentionSpan[];
1402
1432
 
1403
- export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type EditInput, type Frame, type Hello, type MemberRow, type MentionEntity, type MentionSpan, type Message, type MyRoom, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type RoomInfo, RoomList, type RoomListEvents, type RoomSummary, type SendInput, type SendOptions, Thread, type ThreadEvents, type UnreadCounts, type WebSocketFactory, type WebSocketLike, buildMentions, createChatClient, mentionSpans };
1433
+ export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type EditInput, type Frame, type Hello, type MemberRow, type MentionEntity, type MentionSpan, type Message, type MyRoom, type NotificationTyping, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type RoomInfo, RoomList, type RoomListEvents, type RoomSummary, type SendInput, type SendOptions, Thread, type ThreadEvents, type UnreadCounts, type WebSocketFactory, type WebSocketLike, buildMentions, createChatClient, mentionSpans };
package/dist/index.js CHANGED
@@ -2461,6 +2461,10 @@ var ChatClient = class extends Emitter {
2461
2461
  this.emit("notification", push?.data);
2462
2462
  return;
2463
2463
  }
2464
+ if (event === "notification.typing") {
2465
+ this.emit("notification.typing", push?.data);
2466
+ return;
2467
+ }
2464
2468
  if (event === "user.presence") {
2465
2469
  this.emit("user.presence", push?.data);
2466
2470
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kispi/chat",
3
- "version": "0.7.5",
3
+ "version": "0.8.0",
4
4
  "description": "GravEx Chat SDK: managed realtime chat API. One WebSocket, many rooms, ordered history. Get an API key at chat.gravex.app.",
5
5
  "homepage": "https://chat.gravex.app/?utm_source=npm&utm_medium=referral&utm_campaign=sdk_readme",
6
6
  "keywords": [