@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 +30 -2
- package/README.md +29 -2
- package/dist/index.cjs +37 -2
- package/dist/index.d.cts +47 -2
- package/dist/index.d.ts +47 -2
- package/dist/index.js +37 -2
- package/package.json +1 -1
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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
|
|
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
|
-
/**
|
|
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(
|
|
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
|
-
/**
|
|
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(
|
|
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
|
-
|
|
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
|
}
|