@kispi/chat 0.8.1 → 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
@@ -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
@@ -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`)이고,
@@ -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.1",
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": [