@kispi/chat 0.3.1 → 0.4.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
@@ -87,7 +87,8 @@ off()
87
87
  | `react(messageId, emoji)` / `unreact(...)` | Reactions. Idempotent. Updates that row's `myReactions` **before the frame goes out**, and rolls it back if the server refuses. Never touches the count |
88
88
  | `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 |
89
89
  | `markRead(seq, {threadId?})` | Read cursor |
90
- | `typing()` | Typing indicator. Does not throw |
90
+ | `reads({userId?, cursor?, limit?})` | Read cursors, paged. `{reads: [{userId?, seq, threadId?, withdrawn?}], cursor}`. **`userId` narrows to one person** -- `reads({userId: chat.user.id})` recovers your own per-thread cursors. Stop when `cursor` is `''` |
91
+ | `typing({threadId?})` | Typing indicator. Does not throw. Pass `threadId` while writing a thread reply |
91
92
  | `join()` / `leave()` | Membership |
92
93
  | `presenceList()` | Who is in this room right now |
93
94
 
@@ -100,7 +101,7 @@ Event names are **exactly the wire names**, and the payloads are in the type dec
100
101
  | `reaction.added` / `reaction.removed` | `{messageId, emoji, count, userId?}` |
101
102
  | `thread.updated` | `{rootId, count, lastSeq?, lastAt?}` |
102
103
  | `presence` | `{count, joined?, left?, users?, capped?}`. `joined`/`left` are incremental, `users` replaces |
103
- | `typing` | `{userId}` |
104
+ | `typing` | `{userId, threadId?}` -- `threadId` is the thread **root** id, absent for the main timeline |
104
105
  | `read` | `{userId, seq, threadId?}` |
105
106
  | `member.joined` / `member.left` | `{userId, role?}` |
106
107
  | `room.updated` | The room object (`unknown` — the server's own representation) |
@@ -148,6 +149,33 @@ room.on('messages', m => (messages.value = m))
148
149
  - **After a nickname or avatar change, `reconnect()`.** The server reads those values from the
149
150
  token claims once, when the socket authenticates.
150
151
 
152
+ ### `text` is untrusted plain text
153
+
154
+ Message `text`, and user-supplied display names/nicknames (`name`), are **plain text
155
+ the engine does not HTML-escape or sanitize.** This is by design — escaping depends on
156
+ the output context you render into (an HTML text node, an attribute, some other
157
+ format), which the engine cannot decide on your behalf. The engine only **validates**
158
+ (size, shape).
159
+
160
+ So consumers must render it as text — `textContent`, or your framework's text binding
161
+ (React's `{text}`, Svelte's `{text}`, Vue's `{{ text }}`). **Never pass it straight into
162
+ `innerHTML` or `v-html`.** If you add linkification or markup, don't build an HTML
163
+ string with a regex replace — build DOM from text nodes instead.
164
+
165
+ ```ts
166
+ // Don't — builds an HTML string with a regex
167
+ el.innerHTML = text.replace(urlRegex, '<a href="$1">$1</a>')
168
+
169
+ // Do — builds DOM from text nodes
170
+ for (const part of splitByUrl(text)) {
171
+ el.appendChild(part.isUrl ? makeAnchor(part.text) : document.createTextNode(part.text))
172
+ }
173
+ ```
174
+
175
+ Bad-word filtering and similar moderation is not escaping — it's a **tenant policy**.
176
+ The engine only opens the mechanism (the `before_publish` hook); the consumer decides
177
+ (see the `before_publish` section in `docs/protocol.md`).
178
+
151
179
  ### Using it in the browser
152
180
 
153
181
  You **must add the page's origin** to the `pk_`'s allowed origins. That's the only thing —
package/README.md CHANGED
@@ -87,7 +87,8 @@ off()
87
87
  | `react(messageId, emoji)` / `unreact(...)` | 리액션. 멱등. **프레임보다 먼저** 그 행의 `myReactions`를 고치고, 서버가 거절하면 되돌린다. 개수는 건드리지 않는다 |
88
88
  | `reactionsOf(messageId, {emoji?, cursor?, limit?})` | 누가 눌렀는지. **한 행은 (유저, 이모지) 쌍**이라 한 사람이 여러 줄일 수 있다. `limit` 기본 50 최대 100, 마지막 페이지의 `cursor`는 빈 문자열 |
89
89
  | `markRead(seq, {threadId?})` | 읽음 커서 |
90
- | `typing()` | 입력 중. 던지지 않는다 |
90
+ | `reads({userId?, cursor?, limit?})` | 읽음 커서 목록. `{reads: [{userId?, seq, threadId?, withdrawn?}], cursor}`. **`userId`로 한 사람만** — 자기 스레드별 커서를 되찾을 때 `reads({userId: chat.user.id})`. `cursor`가 `''`이면 끝 |
91
+ | `typing({threadId?})` | 입력 중. 던지지 않는다. 스레드 답글을 쓰는 중이면 `threadId` |
91
92
  | `join()` / `leave()` | 멤버십 |
92
93
  | `presenceList()` | 지금 이 방에 있는 사람 |
93
94
 
@@ -100,7 +101,7 @@ off()
100
101
  | `reaction.added` / `reaction.removed` | `{messageId, emoji, count, userId?}` |
101
102
  | `thread.updated` | `{rootId, count, lastSeq?, lastAt?}` |
102
103
  | `presence` | `{count, joined?, left?, users?, capped?}`. `joined`/`left`는 증분, `users`는 교체다 |
103
- | `typing` | `{userId}` |
104
+ | `typing` | `{userId, threadId?}` — `threadId`는 스레드 **루트** id, 본 타임라인이면 없다 |
104
105
  | `read` | `{userId, seq, threadId?}` |
105
106
  | `member.joined` / `member.left` | `{userId, role?}` |
106
107
  | `room.updated` | 방 객체(`unknown` — 서버 표현 그대로다) |
@@ -144,6 +145,32 @@ room.on('messages', m => (messages.value = m))
144
145
  - **닉네임·아바타를 바꿨으면 `reconnect()`.** 서버는 그 값을 접속할 때 토큰 claim에서
145
146
  한 번 읽는다.
146
147
 
148
+ ### `text`는 신뢰할 수 없는 평문이다
149
+
150
+ 메시지 `text`와 유저가 넣는 표시 이름·닉네임(`name`)은 **엔진이 HTML 이스케이프하거나
151
+ 정제하지 않은 평문**이다. 의도적이다 — 이스케이프는 렌더링하는 출력 컨텍스트(HTML
152
+ 텍스트 노드인지, 속성인지, 다른 포맷인지)에 달려 있어 엔진이 대신 정할 수 없다.
153
+ 엔진은 크기·형식 같은 **검증**만 한다.
154
+
155
+ 그래서 소비자가 렌더할 때 텍스트로 다뤄야 한다 — `textContent`나 프레임워크의 텍스트
156
+ 바인딩(React의 `{text}`, Svelte의 `{text}`, Vue의 `{{ text }}`). **`innerHTML`이나
157
+ `v-html`에 그대로 꽂으면 안 된다.** 링크 자동 인식이나 마크업을 더하고 싶으면 문자열을
158
+ HTML로 만들어 정규식으로 치환하지 말고, 텍스트 노드를 만들어 DOM에 직접 붙인다.
159
+
160
+ ```ts
161
+ // 하면 안 된다 — 정규식으로 HTML 문자열을 만든다
162
+ el.innerHTML = text.replace(urlRegex, '<a href="$1">$1</a>')
163
+
164
+ // 이렇게 — 텍스트 노드로 DOM을 만든다
165
+ for (const part of splitByUrl(text)) {
166
+ el.appendChild(part.isUrl ? makeAnchor(part.text) : document.createTextNode(part.text))
167
+ }
168
+ ```
169
+
170
+ 욕설 같은 금칙어 처리는 이스케이프가 아니라 **테넌트 정책**이다 — 엔진은
171
+ `before_publish` 훅이라는 기전만 열어 주고, 판정은 소비자가 한다(`docs/protocol.md`의
172
+ `before_publish` 절).
173
+
147
174
  ### 브라우저에서 쓸 때
148
175
 
149
176
  `pk_`의 허용 오리진에 **페이지의 오리진을 넣어야 한다.** 이것 하나다 — 서버가 CORS 헤더를
package/dist/index.cjs CHANGED
@@ -862,6 +862,32 @@ var Room = class extends Emitter {
862
862
  if (options.threadId !== void 0) data["threadId"] = options.threadId;
863
863
  return await this.chat.sendFrame("read", data);
864
864
  }
865
+ /**
866
+ * Lists read cursors in this room, one page at a time.
867
+ *
868
+ * A row is one (user, scope) pair: the main timeline has no `threadId`,
869
+ * and each thread a user has read is its own row, keyed by the thread's
870
+ * root id. `withdrawn: true` rows carry no `userId`.
871
+ *
872
+ * **`userId` narrows the page to one user**, which is how a client gets
873
+ * its own per-thread positions back after a reload or on another device
874
+ * -- `markRead` writes them, and this reads them:
875
+ *
876
+ * ```ts
877
+ * const mine = await room.reads({ userId: chat.user!.id })
878
+ * ```
879
+ *
880
+ * An id that names no live user returns an empty page. Keep calling
881
+ * with the returned `cursor` while it is non-empty; the last page's
882
+ * cursor is `''`.
883
+ */
884
+ async reads(options = {}) {
885
+ return this.rest.get(`/v1/rooms/${await this.resolveId("reading read cursors")}/reads`, {
886
+ userId: options.userId,
887
+ cursor: options.cursor,
888
+ limit: options.limit
889
+ });
890
+ }
865
891
  /**
866
892
  * Says this user is typing.
867
893
  *
@@ -875,10 +901,19 @@ var Room = class extends Emitter {
875
901
  * filter it out, because a room view that shows every typist and one
876
902
  * that shows everyone else are both legitimate and only the consumer
877
903
  * knows which it is drawing.
904
+ *
905
+ * Pass `threadId` while composing a thread reply. The event carries the
906
+ * thread's **root** id -- a reply's id is normalized to its root, as
907
+ * `send` and `markRead` do -- so a thread panel shows its own typists
908
+ * and the main view can skip them. The server keeps one throttle slot
909
+ * per user per room, not per thread: switching between the main box
910
+ * and a thread is heard up to three seconds late.
878
911
  */
879
- typing() {
912
+ typing(options = {}) {
880
913
  try {
881
- void this.chat.sendFrame("typing", { roomId: this.requireId("typing") }).catch(() => {
914
+ const data = { roomId: this.requireId("typing") };
915
+ if (options.threadId !== void 0) data["threadId"] = options.threadId;
916
+ void this.chat.sendFrame("typing", data).catch(() => {
882
917
  });
883
918
  } catch {
884
919
  }
package/dist/index.d.cts CHANGED
@@ -306,9 +306,13 @@ type RoomEvents = {
306
306
  lastAt?: number;
307
307
  };
308
308
  presence: PresenceEvent;
309
- /** **보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 id를 건너뛴다. */
309
+ /**
310
+ * **보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 id를 건너뛴다.
311
+ * `threadId`는 그 스레드의 **루트** id이고, 본 타임라인에서 입력 중이면 없다.
312
+ */
310
313
  typing: {
311
314
  userId: string;
315
+ threadId?: string;
312
316
  };
313
317
  read: {
314
318
  userId: string;
@@ -503,6 +507,38 @@ declare class Room extends Emitter<RoomEvents> {
503
507
  seq: number;
504
508
  advanced: boolean;
505
509
  }>;
510
+ /**
511
+ * Lists read cursors in this room, one page at a time.
512
+ *
513
+ * A row is one (user, scope) pair: the main timeline has no `threadId`,
514
+ * and each thread a user has read is its own row, keyed by the thread's
515
+ * root id. `withdrawn: true` rows carry no `userId`.
516
+ *
517
+ * **`userId` narrows the page to one user**, which is how a client gets
518
+ * its own per-thread positions back after a reload or on another device
519
+ * -- `markRead` writes them, and this reads them:
520
+ *
521
+ * ```ts
522
+ * const mine = await room.reads({ userId: chat.user!.id })
523
+ * ```
524
+ *
525
+ * An id that names no live user returns an empty page. Keep calling
526
+ * with the returned `cursor` while it is non-empty; the last page's
527
+ * cursor is `''`.
528
+ */
529
+ reads(options?: {
530
+ userId?: string;
531
+ cursor?: string;
532
+ limit?: number;
533
+ }): Promise<{
534
+ reads: {
535
+ userId?: string;
536
+ seq: number;
537
+ threadId?: string;
538
+ withdrawn?: boolean;
539
+ }[];
540
+ cursor: string;
541
+ }>;
506
542
  /**
507
543
  * Says this user is typing.
508
544
  *
@@ -516,8 +552,17 @@ declare class Room extends Emitter<RoomEvents> {
516
552
  * filter it out, because a room view that shows every typist and one
517
553
  * that shows everyone else are both legitimate and only the consumer
518
554
  * knows which it is drawing.
555
+ *
556
+ * Pass `threadId` while composing a thread reply. The event carries the
557
+ * thread's **root** id -- a reply's id is normalized to its root, as
558
+ * `send` and `markRead` do -- so a thread panel shows its own typists
559
+ * and the main view can skip them. The server keeps one throttle slot
560
+ * per user per room, not per thread: switching between the main box
561
+ * and a thread is heard up to three seconds late.
519
562
  */
520
- typing(): void;
563
+ typing(options?: {
564
+ threadId?: string;
565
+ }): void;
521
566
  /** Joins a public or channel room. Idempotent. */
522
567
  join(): Promise<void>;
523
568
  /** Leaves. Idempotent from the caller's side. */
package/dist/index.d.ts CHANGED
@@ -306,9 +306,13 @@ type RoomEvents = {
306
306
  lastAt?: number;
307
307
  };
308
308
  presence: PresenceEvent;
309
- /** **보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 id를 건너뛴다. */
309
+ /**
310
+ * **보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 id를 건너뛴다.
311
+ * `threadId`는 그 스레드의 **루트** id이고, 본 타임라인에서 입력 중이면 없다.
312
+ */
310
313
  typing: {
311
314
  userId: string;
315
+ threadId?: string;
312
316
  };
313
317
  read: {
314
318
  userId: string;
@@ -503,6 +507,38 @@ declare class Room extends Emitter<RoomEvents> {
503
507
  seq: number;
504
508
  advanced: boolean;
505
509
  }>;
510
+ /**
511
+ * Lists read cursors in this room, one page at a time.
512
+ *
513
+ * A row is one (user, scope) pair: the main timeline has no `threadId`,
514
+ * and each thread a user has read is its own row, keyed by the thread's
515
+ * root id. `withdrawn: true` rows carry no `userId`.
516
+ *
517
+ * **`userId` narrows the page to one user**, which is how a client gets
518
+ * its own per-thread positions back after a reload or on another device
519
+ * -- `markRead` writes them, and this reads them:
520
+ *
521
+ * ```ts
522
+ * const mine = await room.reads({ userId: chat.user!.id })
523
+ * ```
524
+ *
525
+ * An id that names no live user returns an empty page. Keep calling
526
+ * with the returned `cursor` while it is non-empty; the last page's
527
+ * cursor is `''`.
528
+ */
529
+ reads(options?: {
530
+ userId?: string;
531
+ cursor?: string;
532
+ limit?: number;
533
+ }): Promise<{
534
+ reads: {
535
+ userId?: string;
536
+ seq: number;
537
+ threadId?: string;
538
+ withdrawn?: boolean;
539
+ }[];
540
+ cursor: string;
541
+ }>;
506
542
  /**
507
543
  * Says this user is typing.
508
544
  *
@@ -516,8 +552,17 @@ declare class Room extends Emitter<RoomEvents> {
516
552
  * filter it out, because a room view that shows every typist and one
517
553
  * that shows everyone else are both legitimate and only the consumer
518
554
  * knows which it is drawing.
555
+ *
556
+ * Pass `threadId` while composing a thread reply. The event carries the
557
+ * thread's **root** id -- a reply's id is normalized to its root, as
558
+ * `send` and `markRead` do -- so a thread panel shows its own typists
559
+ * and the main view can skip them. The server keeps one throttle slot
560
+ * per user per room, not per thread: switching between the main box
561
+ * and a thread is heard up to three seconds late.
519
562
  */
520
- typing(): void;
563
+ typing(options?: {
564
+ threadId?: string;
565
+ }): void;
521
566
  /** Joins a public or channel room. Idempotent. */
522
567
  join(): Promise<void>;
523
568
  /** Leaves. Idempotent from the caller's side. */
package/dist/index.js CHANGED
@@ -792,6 +792,32 @@ var Room = class extends Emitter {
792
792
  if (options.threadId !== void 0) data["threadId"] = options.threadId;
793
793
  return await this.chat.sendFrame("read", data);
794
794
  }
795
+ /**
796
+ * Lists read cursors in this room, one page at a time.
797
+ *
798
+ * A row is one (user, scope) pair: the main timeline has no `threadId`,
799
+ * and each thread a user has read is its own row, keyed by the thread's
800
+ * root id. `withdrawn: true` rows carry no `userId`.
801
+ *
802
+ * **`userId` narrows the page to one user**, which is how a client gets
803
+ * its own per-thread positions back after a reload or on another device
804
+ * -- `markRead` writes them, and this reads them:
805
+ *
806
+ * ```ts
807
+ * const mine = await room.reads({ userId: chat.user!.id })
808
+ * ```
809
+ *
810
+ * An id that names no live user returns an empty page. Keep calling
811
+ * with the returned `cursor` while it is non-empty; the last page's
812
+ * cursor is `''`.
813
+ */
814
+ async reads(options = {}) {
815
+ return this.rest.get(`/v1/rooms/${await this.resolveId("reading read cursors")}/reads`, {
816
+ userId: options.userId,
817
+ cursor: options.cursor,
818
+ limit: options.limit
819
+ });
820
+ }
795
821
  /**
796
822
  * Says this user is typing.
797
823
  *
@@ -805,10 +831,19 @@ var Room = class extends Emitter {
805
831
  * filter it out, because a room view that shows every typist and one
806
832
  * that shows everyone else are both legitimate and only the consumer
807
833
  * knows which it is drawing.
834
+ *
835
+ * Pass `threadId` while composing a thread reply. The event carries the
836
+ * thread's **root** id -- a reply's id is normalized to its root, as
837
+ * `send` and `markRead` do -- so a thread panel shows its own typists
838
+ * and the main view can skip them. The server keeps one throttle slot
839
+ * per user per room, not per thread: switching between the main box
840
+ * and a thread is heard up to three seconds late.
808
841
  */
809
- typing() {
842
+ typing(options = {}) {
810
843
  try {
811
- void this.chat.sendFrame("typing", { roomId: this.requireId("typing") }).catch(() => {
844
+ const data = { roomId: this.requireId("typing") };
845
+ if (options.threadId !== void 0) data["threadId"] = options.threadId;
846
+ void this.chat.sendFrame("typing", data).catch(() => {
812
847
  });
813
848
  } catch {
814
849
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kispi/chat",
3
- "version": "0.3.1",
3
+ "version": "0.4.0",
4
4
  "description": "Client SDK for the chat server: one WebSocket, many rooms, ordered history.",
5
5
  "license": "MIT",
6
6
  "type": "module",