@kispi/chat 0.8.0 → 0.8.2

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,11 +87,11 @@ off()
87
87
 
88
88
  | Method | |
89
89
  |---|---|
90
- | `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()`) |
90
+ | `subscribe()` | Turns on the live feed and reads the latest page (sends no `limit`, so it is **the engine's client default, 20 messages**; if the first screen is not full, keep calling `loadOlder()` while `hasOlder`). Does nothing if already caught up. **Fine to call before connecting** — it waits until connected (rejects with `closed` on `close()`) |
91
91
  | `unsubscribe()` | Stops viewing this room. It is not resubscribed on reconnect |
92
92
  | `send({text, attachments?, entities?, replyTo?, threadId?, meta?}, {clientMessageId?})` | Publish. Acked with `{messageId, seq}`. If a subscription is in progress, it waits for it. **While reconnecting it waits for the connection, then sends** (below) |
93
93
  | `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 |
94
- | `history({before?, after?, limit?, view?})` | Reads the past directly. **Independent of `messages`.** `view` is `'main'`, `'all'`, or `{thread: id}` |
94
+ | `history({before?, after?, limit?, view?})` | Reads the past directly (no `limit` means the engine default of 20, at most 100). **Independent of `messages`.** `view` is `'main'`, `'all'`, or `{thread: id}` |
95
95
  | `thread(rootId, {root?})` | **Thread handle** (`Thread`, below). One per root id, cached until `close()` |
96
96
  | `edit(messageId, {text?, entities?, attachments?})` | Edits your own message. **Replaces the body** — pass back the `attachments`/`entities` to keep. Sender only, within the app's edit window (`forbidden` otherwise). The returned row is applied to `messages` and open threads at once |
97
97
  | `delete(messageId)` | Deletes a message: your own, or anyone's for owners and admins. Idempotent. The row becomes a tombstone at once |
@@ -203,7 +203,7 @@ room.on('messages', m => (messages.value = m))
203
203
  ```
204
204
  - **The connection comes back on its own.** It reconnects with exponential backoff, so don't
205
205
  write your own retry loop.
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.
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 page once (the engine's default, 20 messages; 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 that page 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.
207
207
  - **What you send while reconnecting waits, then goes out.** `send`, `react`, `unreact` and
208
208
  `markRead` skip the backoff when the state is `connecting`/`reconnecting`, wait for the
209
209
  connection, and send. If the socket drops before the ack, **the same frame is sent once more**
@@ -417,7 +417,7 @@ spaces don't overlap.
417
417
 
418
418
  | Group | Methods |
419
419
  |---|---|
420
- | `rooms` | `list({type?, cursor?, limit?})`, `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
420
+ | `rooms` | `list({type?, cursor?, limit?})`, `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete(roomId, {purge?})`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
421
421
  | `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list(roomId, {before?, after?, limit?, view?, q?})`, `delete` |
422
422
  | `users` | `list({cursor?, limit?})`, `update(userId, {name?, avatar?, meta?})`, `withdraw(userId, {purgeMessages?})`, `purgeMessages(userId)`, `ban(userId, {until, reason?})`, `unban(userId)`, `revokeTokens(userId)`, `disconnect(userId, {connectionId?, reason?})` |
423
423
  | `events` | `list({after?, limit?})` — catches up on missed webhook events |
@@ -432,6 +432,9 @@ A search page's seqs are not contiguous; never use them as a sync cursor.
432
432
  defaults to 50 (max 100), an empty `cursor` is the last page, and **the cursor does not carry
433
433
  `type`** — start over when the filter changes.
434
434
 
435
+ `rooms.delete(roomId)` is a soft delete (the messages stay and the `key` is freed). **`rooms.delete(roomId, {purge: true})` deletes permanently** — the room and every message, member and reaction in it are gone and it cannot be undone.
436
+ It returns once the engine accepts the job (202; the `PurgeJob`'s `state` and `deleted` show progress) and the engine deletes in batches. If a purge is already running for the room you get that job back.
437
+
435
438
  `rooms.ensure` is get-or-create — it returns the room as-is if it exists, so it's fine to call
436
439
  on every page load.
437
440
 
package/README.md CHANGED
@@ -86,11 +86,11 @@ off()
86
86
 
87
87
  | 메서드 | |
88
88
  |---|---|
89
- | `subscribe()` | 라이브 피드를 켜고 최근 100건을 읽는다. 이미 따라잡혔으면 아무것도 안 한다. **연결 전에 불러도 된다** — 붙을 때까지 기다린다(`close()`면 `closed`로 거절) |
89
+ | `subscribe()` | 라이브 피드를 켜고 최근 한 페이지를 읽는다(`limit`을 보내지 않아 **엔진의 클라이언트 기본, 20건**이다. 첫 화면이 모자라면 `hasOlder`인 동안 `loadOlder()`로 이어 읽는다). 이미 따라잡혔으면 아무것도 안 한다. **연결 전에 불러도 된다** — 붙을 때까지 기다린다(`close()`면 `closed`로 거절) |
90
90
  | `unsubscribe()` | 이 방 보기를 그만둔다. 재접속해도 다시 구독하지 않는다 |
91
91
  | `send({text, attachments?, entities?, replyTo?, threadId?, meta?}, {clientMessageId?})` | 발행. ack로 `{messageId, seq}`. 구독이 진행 중이면 그것을 기다린다. **재접속 중이면 붙을 때까지 기다렸다가 보낸다**(아래) |
92
92
  | `loadOlder({limit?})` | 가장 오래된 메시지 앞 페이지(기본 100)를 읽어 **`messages` 앞에 붙인다.** `{messages, hasMore}`. 스크롤을 올릴 때 쓴다. 목록이 비어 있으면(구독 전) 아무것도 읽지 않는다 |
93
- | `history({before?, after?, limit?, view?})` | 과거를 직접 읽는다. **`messages`와 따로 논다.** `view`는 `'main'`, `'all'`, `{thread: id}`. 스레드 패널은 `thread()`를 쓴다 |
93
+ | `history({before?, after?, limit?, view?})` | 과거를 직접 읽는다(`limit`을 안 주면 엔진 기본 20건, 최대 100). **`messages`와 따로 논다.** `view`는 `'main'`, `'all'`, `{thread: id}`. 스레드 패널은 `thread()`를 쓴다 |
94
94
  | `thread(rootId, {root?})` | **스레드 핸들**(`Thread`, 아래). 루트 id마다 하나, `close()`까지 캐시된다 |
95
95
  | `edit(messageId, {text?, entities?, attachments?})` | 내 글 고치기. **본문을 통째로 바꾼다** — 남길 `attachments`·`entities`도 다시 넘긴다. 본인만·앱의 수정 가능 시간 안(아니면 `forbidden`). 응답 행(`Message`)을 `messages`와 열린 스레드에 바로 반영한다 |
96
96
  | `delete(messageId)` | 글 지우기. 본인 글, 방장·관리자는 남의 글도. 멱등. 그 행을 바로 tombstone으로 |
@@ -188,9 +188,9 @@ room.on('messages', m => (messages.value = m))
188
188
  })
189
189
  ```
190
190
  - **연결은 알아서 돌아온다.** 끊기면 지수 백오프로 다시 붙으니 재시도 루프를 짜지 않는다.
191
- - **재접속하면 이미 들고 있는 행도 최신으로 맞춘다.** 따라잡기(`since`)는 새 메시지만 채우고, 끊긴 사이 이미 있던 메시지에 붙은 리액션·스레드 수(`thread.updated`)·수정·삭제는 어느 이벤트로도 오지 않는다. 그래서 진짜 재접속(탭·앱 복귀의 재구독 포함, 같은 사람일 때) 뒤 따라잡기가 끝나면 SDK가 **가장 최근 100건을 한 번 읽어(방마다 GET 1번) 들고 있는 행에 합친다.** 목록을 바꾸지 않고(`reset` 없음, `loadOlder()`로 불러 둔 윗부분 그대로) 바뀐 행만 새 객체로 `message.updated`, 지워진 행은 tombstone으로 `message.deleted`를 낸다(`messages`는 한 번). 읽는 사이 도착한 라이브 이벤트나 이 클라이언트가 누른 리액션이 더 새 값이라 그 행은 건드리지 않는다. **최근 100건보다 오래된 행은 다시 읽지 않는다** — 필요하면 `reload()`. 스레드 답글은 같은 타임라인이라 루트와 함께 맞춰진다. 이 읽기가 실패하면 `error`만 나가고 방은 구독된 채다. 소비자가 따로 `reload()`를 부를 필요가 없다.
191
+ - **재접속하면 이미 들고 있는 행도 최신으로 맞춘다.** 따라잡기(`since`)는 새 메시지만 채우고, 끊긴 사이 이미 있던 메시지에 붙은 리액션·스레드 수(`thread.updated`)·수정·삭제는 어느 이벤트로도 오지 않는다. 그래서 진짜 재접속(탭·앱 복귀의 재구독 포함, 같은 사람일 때) 뒤 따라잡기가 끝나면 SDK가 **가장 최근 한 페이지(엔진 기본 20건)를 한 번 읽어(방마다 GET 1번) 들고 있는 행에 합친다.** 목록을 바꾸지 않고(`reset` 없음, `loadOlder()`로 불러 둔 윗부분 그대로) 바뀐 행만 새 객체로 `message.updated`, 지워진 행은 tombstone으로 `message.deleted`를 낸다(`messages`는 한 번). 읽는 사이 도착한 라이브 이벤트나 이 클라이언트가 누른 리액션이 더 새 값이라 그 행은 건드리지 않는다. **그 페이지보다 오래된 행은 다시 읽지 않는다** — 필요하면 `reload()`. 스레드 답글은 같은 타임라인이라 루트와 함께 맞춰진다. 이 읽기가 실패하면 `error`만 나가고 방은 구독된 채다. 소비자가 따로 `reload()`를 부를 필요가 없다.
192
192
  - **떠났던 방을 다시 구독할 때도 같다.** 핸들은 캐시되므로 `unsubscribe()` 뒤 `subscribe()`한 방은 들고 있던
193
- 행을 그대로 받는다. 그래서 다시 구독하면 재접속 때처럼 따라잡은 뒤 최근 100건을 읽어 합친다 — 떠나 있던
193
+ 행을 그대로 받는다. 그래서 다시 구독하면 재접속 때처럼 따라잡은 뒤 최근 한 페이지를 읽어 합친다 — 떠나 있던
194
194
  사이의 리액션·스레드 수가 새로 고침 없이 보인다. 열린 스레드 핸들도 최근 답글 100개를 다시 읽어 합친다.
195
195
  - **재접속 중에 보낸 것은 기다렸다가 나간다.** `send`·`react`·`unreact`·`markRead`는 상태가
196
196
  `connecting`/`reconnecting`이면 백오프를 건너뛰고 붙기를 기다려 보낸다. ack 전에 소켓이
@@ -406,12 +406,15 @@ app.post('/api/chat-token', (req, res) => {
406
406
 
407
407
  | 그룹 | 메서드 |
408
408
  |---|---|
409
- | `rooms` | `list({type?, cursor?, limit?})`, `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
409
+ | `rooms` | `list({type?, cursor?, limit?})`, `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete(roomId, {purge?})`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
410
410
  | `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list(roomId, {before?, after?, limit?, view?, q?})`, `delete` |
411
411
  | `users` | `list({cursor?, limit?})`, `update(userId, {name?, avatar?, meta?})`, `withdraw(userId, {purgeMessages?})`, `purgeMessages(userId)`, `ban(userId, {until, reason?})`, `unban(userId)`, `revokeTokens(userId)`, `disconnect(userId, {connectionId?, reason?})` |
412
412
  | `events` | `list({after?, limit?})` — 놓친 웹훅 이벤트를 따라잡는다 |
413
413
  | `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` — `tolerance`는 밀리초 |
414
414
 
415
+ `rooms.delete(roomId)`는 소프트 삭제다(메시지는 남고 `key`가 비워진다). **`rooms.delete(roomId, {purge: true})`는 영구 삭제다** — 방과 그 안의 모든 메시지·멤버·리액션이 사라지고 되돌릴 수 없다.
416
+ 202로 접수되면 곧바로 돌아오고(`PurgeJob` — `state`·`deleted`가 진행을 보여 준다) 지우는 건 엔진이 배치로 한다. 같은 방에 진행 중인 작업이 있으면 그 작업을 돌려준다.
417
+
415
418
  `rooms.ensure`는 get-or-create다 — 있으면 그대로 돌려주므로 페이지를 열 때마다 불러도 된다.
416
419
 
417
420
  `rooms.list`는 앱의 방을 최신순으로 준다. `type`이 없으면 공개 목록(`public`·`channel`)이고,
package/dist/index.cjs CHANGED
@@ -945,7 +945,6 @@ var Thread = class extends Emitter {
945
945
  };
946
946
 
947
947
  // src/room.ts
948
- var HistoryPageSize = 100;
949
948
  var TypingSendIntervalMs = 1e3;
950
949
  var TypingTtlMs = 5e3;
951
950
  var MaxRepairs = 5;
@@ -1137,7 +1136,7 @@ var Room = class extends Emitter {
1137
1136
  *
1138
1137
  * A reconnect already brings the held rows up to date by itself: after
1139
1138
  * the catch-up it re-reads the newest page (one `GET .../messages`,
1140
- * `limit=100`) and **merges** it into the rows it holds -- reactions,
1139
+ * no `limit`, so the engine's default page for a client, 20) and **merges** it into the rows it holds -- reactions,
1141
1140
  * `myReactions`, thread counts, edits and deletes that happened while
1142
1141
  * the socket was away -- see `refreshHeld`. Reactions, thread counts and
1143
1142
  * the like ride on history rows only, and no event replays them, so
@@ -1228,7 +1227,7 @@ var Room = class extends Emitter {
1228
1227
  * What a reconnect's catch-up cannot bring: it fetches rows this client
1229
1228
  * does not have, and a reaction, a thread count, an edit or a delete that
1230
1229
  * happened to a row it **does** have rides on no event it will see. One
1231
- * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
1230
+ * `GET .../messages` per reconnect (no `limit`: the engine's default page, 20), so the newest rows of
1232
1231
  * the room are refreshed and anything older is not -- that is the bound
1233
1232
  * on the cost, and it is the part of the room people are looking at.
1234
1233
  * Thread replies live in the same timeline, so they and their roots come
@@ -1250,9 +1249,7 @@ var Room = class extends Emitter {
1250
1249
  if (this.timeline.messages.length === 0) return;
1251
1250
  const handle = this.timeline.beginRefresh();
1252
1251
  try {
1253
- const page = await this.rest.get(`/v1/rooms/${this.requireId("refreshing history")}/messages`, {
1254
- limit: HistoryPageSize
1255
- });
1252
+ const page = await this.rest.get(`/v1/rooms/${this.requireId("refreshing history")}/messages`);
1256
1253
  if (!stillCurrent()) return;
1257
1254
  const { updated, deleted } = this.timeline.applyRefresh(handle, page.messages);
1258
1255
  for (const m of updated) this.emit("message.updated", m);
@@ -1679,6 +1676,10 @@ var Room = class extends Emitter {
1679
1676
  /**
1680
1677
  * Replaces the timeline with the most recent page.
1681
1678
  *
1679
+ * No `limit` is sent: the page size is the engine's default for a client
1680
+ * (20), so it can be tuned in one place. A caller that wants more says so
1681
+ * with `loadOlder({ limit })`.
1682
+ *
1682
1683
  * `stillCurrent` guards the write, not the read. This is a replacement
1683
1684
  * -- the whole point of it -- so a page fetched for a socket that has
1684
1685
  * since died would throw away everything the socket that replaced it
@@ -1687,9 +1688,7 @@ var Room = class extends Emitter {
1687
1688
  * has to cover the part that touches shared state.
1688
1689
  */
1689
1690
  async loadRecent(stillCurrent) {
1690
- const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`, {
1691
- limit: HistoryPageSize
1692
- });
1691
+ const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`);
1693
1692
  if (!stillCurrent()) return;
1694
1693
  this.timeline.reset(page.messages);
1695
1694
  }
package/dist/index.d.cts CHANGED
@@ -622,7 +622,7 @@ declare class Room extends Emitter<RoomEvents> {
622
622
  *
623
623
  * A reconnect already brings the held rows up to date by itself: after
624
624
  * the catch-up it re-reads the newest page (one `GET .../messages`,
625
- * `limit=100`) and **merges** it into the rows it holds -- reactions,
625
+ * no `limit`, so the engine's default page for a client, 20) and **merges** it into the rows it holds -- reactions,
626
626
  * `myReactions`, thread counts, edits and deletes that happened while
627
627
  * the socket was away -- see `refreshHeld`. Reactions, thread counts and
628
628
  * the like ride on history rows only, and no event replays them, so
@@ -652,7 +652,7 @@ declare class Room extends Emitter<RoomEvents> {
652
652
  * What a reconnect's catch-up cannot bring: it fetches rows this client
653
653
  * does not have, and a reaction, a thread count, an edit or a delete that
654
654
  * happened to a row it **does** have rides on no event it will see. One
655
- * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
655
+ * `GET .../messages` per reconnect (no `limit`: the engine's default page, 20), so the newest rows of
656
656
  * the room are refreshed and anything older is not -- that is the bound
657
657
  * on the cost, and it is the part of the room people are looking at.
658
658
  * Thread replies live in the same timeline, so they and their roots come
@@ -869,6 +869,10 @@ declare class Room extends Emitter<RoomEvents> {
869
869
  /**
870
870
  * Replaces the timeline with the most recent page.
871
871
  *
872
+ * No `limit` is sent: the page size is the engine's default for a client
873
+ * (20), so it can be tuned in one place. A caller that wants more says so
874
+ * with `loadOlder({ limit })`.
875
+ *
872
876
  * `stillCurrent` guards the write, not the read. This is a replacement
873
877
  * -- the whole point of it -- so a page fetched for a socket that has
874
878
  * since died would throw away everything the socket that replaced it
package/dist/index.d.ts CHANGED
@@ -622,7 +622,7 @@ declare class Room extends Emitter<RoomEvents> {
622
622
  *
623
623
  * A reconnect already brings the held rows up to date by itself: after
624
624
  * the catch-up it re-reads the newest page (one `GET .../messages`,
625
- * `limit=100`) and **merges** it into the rows it holds -- reactions,
625
+ * no `limit`, so the engine's default page for a client, 20) and **merges** it into the rows it holds -- reactions,
626
626
  * `myReactions`, thread counts, edits and deletes that happened while
627
627
  * the socket was away -- see `refreshHeld`. Reactions, thread counts and
628
628
  * the like ride on history rows only, and no event replays them, so
@@ -652,7 +652,7 @@ declare class Room extends Emitter<RoomEvents> {
652
652
  * What a reconnect's catch-up cannot bring: it fetches rows this client
653
653
  * does not have, and a reaction, a thread count, an edit or a delete that
654
654
  * happened to a row it **does** have rides on no event it will see. One
655
- * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
655
+ * `GET .../messages` per reconnect (no `limit`: the engine's default page, 20), so the newest rows of
656
656
  * the room are refreshed and anything older is not -- that is the bound
657
657
  * on the cost, and it is the part of the room people are looking at.
658
658
  * Thread replies live in the same timeline, so they and their roots come
@@ -869,6 +869,10 @@ declare class Room extends Emitter<RoomEvents> {
869
869
  /**
870
870
  * Replaces the timeline with the most recent page.
871
871
  *
872
+ * No `limit` is sent: the page size is the engine's default for a client
873
+ * (20), so it can be tuned in one place. A caller that wants more says so
874
+ * with `loadOlder({ limit })`.
875
+ *
872
876
  * `stillCurrent` guards the write, not the read. This is a replacement
873
877
  * -- the whole point of it -- so a page fetched for a socket that has
874
878
  * since died would throw away everything the socket that replaced it
package/dist/index.js CHANGED
@@ -871,7 +871,6 @@ var Thread = class extends Emitter {
871
871
  };
872
872
 
873
873
  // src/room.ts
874
- var HistoryPageSize = 100;
875
874
  var TypingSendIntervalMs = 1e3;
876
875
  var TypingTtlMs = 5e3;
877
876
  var MaxRepairs = 5;
@@ -1063,7 +1062,7 @@ var Room = class extends Emitter {
1063
1062
  *
1064
1063
  * A reconnect already brings the held rows up to date by itself: after
1065
1064
  * the catch-up it re-reads the newest page (one `GET .../messages`,
1066
- * `limit=100`) and **merges** it into the rows it holds -- reactions,
1065
+ * no `limit`, so the engine's default page for a client, 20) and **merges** it into the rows it holds -- reactions,
1067
1066
  * `myReactions`, thread counts, edits and deletes that happened while
1068
1067
  * the socket was away -- see `refreshHeld`. Reactions, thread counts and
1069
1068
  * the like ride on history rows only, and no event replays them, so
@@ -1154,7 +1153,7 @@ var Room = class extends Emitter {
1154
1153
  * What a reconnect's catch-up cannot bring: it fetches rows this client
1155
1154
  * does not have, and a reaction, a thread count, an edit or a delete that
1156
1155
  * happened to a row it **does** have rides on no event it will see. One
1157
- * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
1156
+ * `GET .../messages` per reconnect (no `limit`: the engine's default page, 20), so the newest rows of
1158
1157
  * the room are refreshed and anything older is not -- that is the bound
1159
1158
  * on the cost, and it is the part of the room people are looking at.
1160
1159
  * Thread replies live in the same timeline, so they and their roots come
@@ -1176,9 +1175,7 @@ var Room = class extends Emitter {
1176
1175
  if (this.timeline.messages.length === 0) return;
1177
1176
  const handle = this.timeline.beginRefresh();
1178
1177
  try {
1179
- const page = await this.rest.get(`/v1/rooms/${this.requireId("refreshing history")}/messages`, {
1180
- limit: HistoryPageSize
1181
- });
1178
+ const page = await this.rest.get(`/v1/rooms/${this.requireId("refreshing history")}/messages`);
1182
1179
  if (!stillCurrent()) return;
1183
1180
  const { updated, deleted } = this.timeline.applyRefresh(handle, page.messages);
1184
1181
  for (const m of updated) this.emit("message.updated", m);
@@ -1605,6 +1602,10 @@ var Room = class extends Emitter {
1605
1602
  /**
1606
1603
  * Replaces the timeline with the most recent page.
1607
1604
  *
1605
+ * No `limit` is sent: the page size is the engine's default for a client
1606
+ * (20), so it can be tuned in one place. A caller that wants more says so
1607
+ * with `loadOlder({ limit })`.
1608
+ *
1608
1609
  * `stillCurrent` guards the write, not the read. This is a replacement
1609
1610
  * -- the whole point of it -- so a page fetched for a socket that has
1610
1611
  * since died would throw away everything the socket that replaced it
@@ -1613,9 +1614,7 @@ var Room = class extends Emitter {
1613
1614
  * has to cover the part that touches shared state.
1614
1615
  */
1615
1616
  async loadRecent(stillCurrent) {
1616
- const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`, {
1617
- limit: HistoryPageSize
1618
- });
1617
+ const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`);
1619
1618
  if (!stillCurrent()) return;
1620
1619
  this.timeline.reset(page.messages);
1621
1620
  }
@@ -298,9 +298,13 @@ function createChatServer(options) {
298
298
  ensureDM: (members) => rest.call("PUT", "/v1/rooms", { type: "dm", members }),
299
299
  get: (roomId) => rest.call("GET", `/v1/rooms/${roomId}`),
300
300
  update: (roomId, patch) => rest.call("PATCH", `/v1/rooms/${roomId}`, patch),
301
- delete: async (roomId) => {
301
+ delete: (async (roomId, o) => {
302
+ if (o?.purge === true) {
303
+ const res = await rest.call("DELETE", `/v1/rooms/${roomId}${rest.query({ purge: "true" })}`);
304
+ return res.job;
305
+ }
302
306
  await rest.call("DELETE", `/v1/rooms/${roomId}`);
303
- },
307
+ }),
304
308
  custom: async (roomId, payload) => {
305
309
  await rest.call("POST", `/v1/rooms/${roomId}/custom`, { payload });
306
310
  },
@@ -115,6 +115,21 @@ type RoomPresence = {
115
115
  }[];
116
116
  capped?: boolean;
117
117
  };
118
+ /** A purge job, as `rooms.delete(id, { purge: true })` returns it. Times are RFC 3339 strings. */
119
+ type PurgeJob = {
120
+ id: string;
121
+ kind: 'app' | 'room' | 'user';
122
+ targetId: string;
123
+ /** `failed` is not final: the worker retries it. */
124
+ state: 'pending' | 'running' | 'done' | 'failed';
125
+ requestedAt: string;
126
+ startedAt: string | null;
127
+ finishedAt: string | null;
128
+ error: string | null;
129
+ /** Table name to rows removed so far. */
130
+ deleted: Record<string, number>;
131
+ attempts: number;
132
+ };
118
133
  /** What `users.purgeMessages` and the withdrawal purge report. */
119
134
  type PurgeMessagesResult = {
120
135
  userId: string;
@@ -183,7 +198,26 @@ type ChatServer = {
183
198
  name?: string;
184
199
  meta?: Record<string, unknown>;
185
200
  }) => Promise<unknown>;
186
- delete: (roomId: string) => Promise<void>;
201
+ /**
202
+ * Soft-deletes the room: 204, subscribers get `room.deleted`, the room
203
+ * 404s and its `key` is free again. The messages stay.
204
+ *
205
+ * `{ purge: true }` deletes it **permanently** (`?purge=true`): the
206
+ * room is soft-deleted first if it is alive, then a purge job removes
207
+ * the room and every message, member and reaction in it. It cannot be
208
+ * undone. The call returns once the job is accepted (202), not when the
209
+ * rows are gone -- the returned job says how far it got. A purge already
210
+ * running for the room answers with that same job.
211
+ */
212
+ delete: {
213
+ (roomId: string): Promise<void>;
214
+ (roomId: string, options: {
215
+ purge: true;
216
+ }): Promise<PurgeJob>;
217
+ (roomId: string, options?: {
218
+ purge?: boolean;
219
+ }): Promise<PurgeJob | void>;
220
+ };
187
221
  /**
188
222
  * Broadcasts an app-authored `custom` event into the room.
189
223
  *
@@ -330,4 +364,4 @@ type ChatServer = {
330
364
  };
331
365
  declare function createChatServer(options: ChatServerOptions): ChatServer;
332
366
 
333
- export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type PurgeMessagesResult, type RoomPresence, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
367
+ export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type PurgeJob, type PurgeMessagesResult, type RoomPresence, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
@@ -115,6 +115,21 @@ type RoomPresence = {
115
115
  }[];
116
116
  capped?: boolean;
117
117
  };
118
+ /** A purge job, as `rooms.delete(id, { purge: true })` returns it. Times are RFC 3339 strings. */
119
+ type PurgeJob = {
120
+ id: string;
121
+ kind: 'app' | 'room' | 'user';
122
+ targetId: string;
123
+ /** `failed` is not final: the worker retries it. */
124
+ state: 'pending' | 'running' | 'done' | 'failed';
125
+ requestedAt: string;
126
+ startedAt: string | null;
127
+ finishedAt: string | null;
128
+ error: string | null;
129
+ /** Table name to rows removed so far. */
130
+ deleted: Record<string, number>;
131
+ attempts: number;
132
+ };
118
133
  /** What `users.purgeMessages` and the withdrawal purge report. */
119
134
  type PurgeMessagesResult = {
120
135
  userId: string;
@@ -183,7 +198,26 @@ type ChatServer = {
183
198
  name?: string;
184
199
  meta?: Record<string, unknown>;
185
200
  }) => Promise<unknown>;
186
- delete: (roomId: string) => Promise<void>;
201
+ /**
202
+ * Soft-deletes the room: 204, subscribers get `room.deleted`, the room
203
+ * 404s and its `key` is free again. The messages stay.
204
+ *
205
+ * `{ purge: true }` deletes it **permanently** (`?purge=true`): the
206
+ * room is soft-deleted first if it is alive, then a purge job removes
207
+ * the room and every message, member and reaction in it. It cannot be
208
+ * undone. The call returns once the job is accepted (202), not when the
209
+ * rows are gone -- the returned job says how far it got. A purge already
210
+ * running for the room answers with that same job.
211
+ */
212
+ delete: {
213
+ (roomId: string): Promise<void>;
214
+ (roomId: string, options: {
215
+ purge: true;
216
+ }): Promise<PurgeJob>;
217
+ (roomId: string, options?: {
218
+ purge?: boolean;
219
+ }): Promise<PurgeJob | void>;
220
+ };
187
221
  /**
188
222
  * Broadcasts an app-authored `custom` event into the room.
189
223
  *
@@ -330,4 +364,4 @@ type ChatServer = {
330
364
  };
331
365
  declare function createChatServer(options: ChatServerOptions): ChatServer;
332
366
 
333
- export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type PurgeMessagesResult, type RoomPresence, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
367
+ export { type ChatServer, type ChatServerOptions, DefaultTokenTtlSeconds, type EnsureRoomInput, GuestIdPrefix, type GuestIdentity, type GuestInput, MaxTokenTtlSeconds, type PurgeJob, type PurgeMessagesResult, type RoomPresence, type ServerSendInput, SignatureToleranceMs, type TokenInput, type VerifiedDelivery, type VerifyOptions, createChatServer };
@@ -227,9 +227,13 @@ function createChatServer(options) {
227
227
  ensureDM: (members) => rest.call("PUT", "/v1/rooms", { type: "dm", members }),
228
228
  get: (roomId) => rest.call("GET", `/v1/rooms/${roomId}`),
229
229
  update: (roomId, patch) => rest.call("PATCH", `/v1/rooms/${roomId}`, patch),
230
- delete: async (roomId) => {
230
+ delete: (async (roomId, o) => {
231
+ if (o?.purge === true) {
232
+ const res = await rest.call("DELETE", `/v1/rooms/${roomId}${rest.query({ purge: "true" })}`);
233
+ return res.job;
234
+ }
231
235
  await rest.call("DELETE", `/v1/rooms/${roomId}`);
232
- },
236
+ }),
233
237
  custom: async (roomId, payload) => {
234
238
  await rest.call("POST", `/v1/rooms/${roomId}/custom`, { payload });
235
239
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kispi/chat",
3
- "version": "0.8.0",
3
+ "version": "0.8.2",
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": [