@noverachat/sdk-web 0.0.3 → 0.2.0

package/src/features/room.ts

@@ -19,6 +19,7 @@ import type {
   InviteToken,
   MessageIdStr,
   MessageOut,
+  RoomMemberOut,
   RoomUnread,
   SendFileOptions,
   SendParams,
@@ -34,67 +35,69 @@ import type {
 } from "../types.js";
 import { EventBus } from "../internal/event-bus.js";
 import { tempId as newTempId } from "../internal/temp-id.js";
+import {
+  parseAnnouncementOut,
+  parseBulkDeleteBySenderResult,
+  parseBulkDeleteResult,
+  parseFileCreateResponse,
+  parseFileOut,
+  parseInviteTokenOut,
+  parseJoinRequestCreateResponse,
+  parseJoinRequestListResponse,
+  parseMessageOut,
+  parseRoomMemberOut,
+  parseRoomUnread,
+} from "../generated/rest.js";
+import type {
+  JoinRequestCreateResponse,
+  JoinRequestListResponse,
+} from "../generated/rest.js";
 // Note: previously used `utils/debounce`, replaced with a hand-rolled
 // timer in Room so we can also expose `flushMarkRead()` — the util has
 // no flush primitive.
 
-// Shape coming off the wire from /api/v1/rooms/{id}/messages — backend is
-// Pydantic v2 with snake_case AND serializes 63-bit ids as JSON strings
-// (see `MsgId` on the server). Kept private to this module; callers see
-// the camelCase MessageOut exported from types.ts with string ids.
-interface RawMessageOut {
-  app_id: string;
-  room_id: string;
-  message_id: string;
-  sender: { user_id: string; nickname?: string | null; profile_image_url?: string | null } | null;
-  sender_id: string | null;
-  message_type: MessageOut["messageType"];
-  custom_type?: string | null;
-  content?: string | null;
-  data?: Record<string, unknown> | null;
-  meta?: Record<string, unknown> | null;
-  file_id?: string | null;
-  file?: {
-    id: string;
-    kind: "image" | "video" | "file";
-    mime: string;
-    size: number;
-    name?: string | null;
-    width?: number | null;
-    height?: number | null;
-    duration_sec?: number | null;
-    thumbnail_status: "pending" | "ready" | "failed" | "skipped";
-    forward_blocked?: boolean;
-  } | null;
-  files?: Array<{
-    id: string;
-    kind: "image" | "video" | "file";
-    mime: string;
-    size: number;
-    name?: string | null;
-    width?: number | null;
-    height?: number | null;
-    duration_sec?: number | null;
-    thumbnail_status: "pending" | "ready" | "failed" | "skipped";
-    forward_blocked?: boolean;
-  }> | null;
-  reply_to_id?: string | null;
-  reactions?: Array<{ key: string; user_ids: string[]; updated_at: number }>;
-  created_at: string;
-  created_at_ms: number;
-  updated_at?: string | null;
-  updated_at_ms?: number | null;
-  deleted_at?: string | null;
-  deleted_by_user_id?: string | null;
-  delete_scope?: MessageOut["deleteScope"] | null;
-  edited_count?: number;
+// Inline file metadata as it rides on a message (chat_receive / REST
+// history). The generated REST `MessageOut` leaves `file`/`files` free-form
+// (the OpenAPI schema does), so we fold the snake_case wire shape down to
+// the camelCase `FileInline` here — mirrors `FileInlineWire` in wire.ts.
+function toFileInline(f: {
+  id: string;
+  kind: FileKind;
+  mime: string;
+  size: number;
+  name?: string | null;
+  width?: number | null;
+  height?: number | null;
+  duration_sec?: number | null;
+  thumbnail_status: FileMeta["thumbnailStatus"];
+  forward_blocked?: boolean;
+}): FileMeta {
+  return {
+    id: f.id,
+    kind: f.kind,
+    mime: f.mime,
+    size: f.size,
+    name: f.name ?? null,
+    width: f.width ?? null,
+    height: f.height ?? null,
+    durationSec: f.duration_sec ?? null,
+    thumbnailStatus: f.thumbnail_status,
+    forwardBlocked: Boolean(f.forward_blocked),
+  };
 }
 
-function toMessageOut(r: RawMessageOut): MessageOut {
-  // Phase D #11 — extract sender-attached `_customMeta` from `data`.
-  // Backend stores the whole `data` blob untouched, so both self-sent
-  // and received messages surface `customMeta` here for the caller.
-  const dataObj = r.data ?? null;
+// Enhance the GENERATED `parseMessageOut` with the two client-side
+// extras it can't derive from the OpenAPI schema: parse `file`/`files`
+// into the camelCase `FileInline` shape, and lift sender-attached
+// `_customMeta` out of `data` (Phase D #11). Everything else — key
+// renames, nested sender/reactions — comes straight from the codegen.
+function toMessageOut(j: unknown): MessageOut {
+  const base = parseMessageOut(j);
+  const raw = j as {
+    file?: Parameters<typeof toFileInline>[0] | null;
+    files?: Parameters<typeof toFileInline>[0][] | null;
+  };
+  const dataObj = base.data ?? null;
   const customMeta =
     dataObj && typeof dataObj === "object" && "_customMeta" in dataObj
       ? ((dataObj as Record<string, unknown>)._customMeta as
@@ -102,66 +105,12 @@ function toMessageOut(r: RawMessageOut): MessageOut {
           | null)
       : null;
   return {
-    appId: r.app_id,
-    roomId: r.room_id,
-    messageId: r.message_id,
-    sender: r.sender
-      ? {
-          userId: r.sender.user_id,
-          nickname: r.sender.nickname ?? null,
-          profileImageUrl: r.sender.profile_image_url ?? null,
-        }
-      : null,
-    senderId: r.sender_id ?? null,
-    messageType: r.message_type,
-    customType: r.custom_type ?? null,
-    content: r.content ?? null,
-    data: dataObj,
-    meta: r.meta ?? null,
+    ...base,
+    file: raw.file ? toFileInline(raw.file) : null,
+    files:
+      raw.files && raw.files.length > 0 ? raw.files.map(toFileInline) : null,
+    reactions: base.reactions ?? [],
     customMeta,
-    fileId: r.file_id ?? null,
-    file: r.file
-      ? {
-          id: r.file.id,
-          kind: r.file.kind,
-          mime: r.file.mime,
-          size: r.file.size,
-          name: r.file.name ?? null,
-          width: r.file.width ?? null,
-          height: r.file.height ?? null,
-          durationSec: r.file.duration_sec ?? null,
-          thumbnailStatus: r.file.thumbnail_status,
-          forwardBlocked: Boolean(r.file.forward_blocked),
-        }
-      : null,
-    files: r.files && r.files.length > 0
-      ? r.files.map((f) => ({
-          id: f.id,
-          kind: f.kind,
-          mime: f.mime,
-          size: f.size,
-          name: f.name ?? null,
-          width: f.width ?? null,
-          height: f.height ?? null,
-          durationSec: f.duration_sec ?? null,
-          thumbnailStatus: f.thumbnail_status,
-          forwardBlocked: Boolean(f.forward_blocked),
-        }))
-      : null,
-    replyToId: r.reply_to_id ?? null,
-    reactions: (r.reactions ?? []).map((x) => ({
-      key: x.key,
-      userIds: x.user_ids,
-      updatedAt: x.updated_at,
-    })),
-    createdAt: r.created_at,
-    createdAtMs: r.created_at_ms,
-    updatedAt: r.updated_at ?? null,
-    updatedAtMs: r.updated_at_ms ?? null,
-    deletedAt: r.deleted_at ?? null,
-    deletedByUserId: r.deleted_by_user_id ?? null,
-    deleteScope: r.delete_scope ?? null,
-    editedCount: r.edited_count ?? 0,
   };
 }
 
@@ -446,25 +395,24 @@ export class Room {
     // Step 1 — presign. The backend assigns the file_id and the S3 key
     // and returns the URL we should PUT to. ``Content-Type`` is bound
     // into the signature, so the PUT must echo it.
-    const presign = await this.http.request<{
-      file_id: MessageIdStr;
-      upload_url: string;
-      headers: Record<string, string>;
-      expires_at_ms: number;
-    }>("POST", "/api/v1/files", {
-      kind,
-      mime: file.type || "application/octet-stream",
-      size: file.size,
-      original_name: name,
-      // 파일 전달 제한 — uploader-set at presign time. When true,
-      // other users can't forward this file to a different room.
-      forward_blocked: Boolean(opts.forwardBlocked),
-    });
+    const created = parseFileCreateResponse(
+      await this.http.request<unknown>("POST", "/api/v1/files", {
+        kind,
+        mime: file.type || "application/octet-stream",
+        size: file.size,
+        original_name: name,
+        // 파일 전달 제한 — uploader-set at presign time. When true,
+        // other users can't forward this file to a different room.
+        forward_blocked: Boolean(opts.forwardBlocked),
+      }),
+    );
     const presigned: FilePresignResponse = {
-      fileId: presign.file_id,
-      uploadUrl: presign.upload_url,
-      headers: presign.headers,
-      expiresAtMs: presign.expires_at_ms,
+      fileId: created.fileId,
+      uploadUrl: created.uploadUrl,
+      // Presigned S3 headers are always string-valued; the generated
+      // model types the JSON object loosely as Record<string, unknown>.
+      headers: created.headers as Record<string, string>,
+      expiresAtMs: created.expiresAtMs,
     };
 
     // Step 2 — S3 PUT via XHR so the caller can show a progress bar.
@@ -542,24 +490,21 @@ export class Room {
         : "file");
     const name = opts.name ?? file.name;
 
-    const presign = await this.http.request<{
-      file_id: MessageIdStr;
-      upload_url: string;
-      headers: Record<string, string>;
-      expires_at_ms: number;
-    }>("POST", "/api/v1/files", {
-      kind,
-      mime: file.type || "application/octet-stream",
-      size: file.size,
-      original_name: name,
-      forward_blocked: Boolean(opts.forwardBlocked),
-    });
+    const created = parseFileCreateResponse(
+      await this.http.request<unknown>("POST", "/api/v1/files", {
+        kind,
+        mime: file.type || "application/octet-stream",
+        size: file.size,
+        original_name: name,
+        forward_blocked: Boolean(opts.forwardBlocked),
+      }),
+    );
 
     await new Promise<void>((resolve, reject) => {
       const xhr = new XMLHttpRequest();
-      xhr.open("PUT", presign.upload_url);
-      for (const [k, v] of Object.entries(presign.headers)) {
-        xhr.setRequestHeader(k, v);
+      xhr.open("PUT", created.uploadUrl);
+      for (const [k, v] of Object.entries(created.headers)) {
+        xhr.setRequestHeader(k, v as string);
       }
       if (opts.onProgress) {
         xhr.upload.addEventListener("progress", (e) => {
@@ -585,9 +530,9 @@ export class Room {
     });
 
     await this.http.request<FileMeta>(
-      "POST", `/api/v1/files/${presign.file_id}/commit`, {},
+      "POST", `/api/v1/files/${created.fileId}/commit`, {},
     );
-    return presign.file_id;
+    return created.fileId;
   }
 
   /**
@@ -619,18 +564,7 @@ export class Room {
         message_id: MessageIdStr;
         sender_id: string | null;
         created_at_ms: number;
-        file: {
-          id: MessageIdStr;
-          kind: FileKind;
-          mime: string;
-          size_bytes: number;
-          original_name: string | null;
-          width: number | null;
-          height: number | null;
-          duration_sec: number | null;
-          thumbnail_status: FileMeta["thumbnailStatus"];
-          forward_blocked?: boolean;
-        };
+        file: unknown;
       }>;
       next_cursor: MessageIdStr | null;
       has_more: boolean;
@@ -644,23 +578,29 @@ export class Room {
       },
     );
     return {
-      items: raw.items.map((r) => ({
-        messageId: r.message_id,
-        senderId: r.sender_id,
-        createdAtMs: r.created_at_ms,
-        file: {
-          id: r.file.id,
-          kind: r.file.kind,
-          mime: r.file.mime,
-          size: r.file.size_bytes,
-          name: r.file.original_name ?? null,
-          width: r.file.width ?? null,
-          height: r.file.height ?? null,
-          durationSec: r.file.duration_sec ?? null,
-          thumbnailStatus: r.file.thumbnail_status,
-          forwardBlocked: Boolean(r.file.forward_blocked),
-        },
-      })),
+      items: raw.items.map((r) => {
+        // Per-file payload is the generated ``FileOut`` shape — parse it
+        // with the codegen'd converter, then fold to the leaner
+        // ``FileMeta`` (= FileInline) the SDK surfaces.
+        const f = parseFileOut(r.file);
+        return {
+          messageId: r.message_id,
+          senderId: r.sender_id,
+          createdAtMs: r.created_at_ms,
+          file: {
+            id: f.id,
+            kind: f.kind,
+            mime: f.mime,
+            size: f.sizeBytes,
+            name: f.originalName ?? null,
+            width: f.width ?? null,
+            height: f.height ?? null,
+            durationSec: f.durationSec ?? null,
+            thumbnailStatus: f.thumbnailStatus,
+            forwardBlocked: Boolean(f.forwardBlocked),
+          },
+        };
+      }),
       nextCursor: raw.next_cursor,
       hasMore: raw.has_more,
     };
@@ -706,9 +646,10 @@ export class Room {
     messageId: MessageIdStr,
     patch: { content?: string; data?: Record<string, unknown>; meta?: Record<string, unknown> },
   ): Promise<MessageOut> {
-    return this.http.request<MessageOut>(
+    const raw = await this.http.request<unknown>(
       "PUT", `/api/v1/rooms/${this.roomId}/messages/${messageId}`, patch,
     );
+    return toMessageOut(raw);
   }
 
   async delete(messageId: MessageIdStr, scope: DeleteScope = "ALL"): Promise<void> {
@@ -733,11 +674,40 @@ export class Room {
    *  Other members get a `MEMBER_LEFT` [`roomEvent`](../reference/noverachat.md#events).
    *  Idempotent if already a non-member; throws 409 if the caller was KICKED
    *  (ask an operator to restore first). For GROUP/SUPER_GROUP, re-entry needs
-   *  an operator add; for ONE, re-creating the 1:1 rejoins with history kept. */
-  async leave(): Promise<void> {
+   *  an operator add; for ONE, re-creating the 1:1 rejoins with history kept.
+   *
+   *  Optional `deleteMessages` — atomically clean up chat history as part
+   *  of leaving.  Default is `"none"` (messages survive so the room's
+   *  history keeps making sense to remaining members).
+   *    - `"none"` — leave only.
+   *    - `"mine"` — soft-delete every message YOU sent, then leave.  Other
+   *                 members' messages are untouched.  Broadcasts
+   *                 `messages_cleared_by_sender` so connected clients hide
+   *                 them locally.
+   *    - `"all"`  — wipe every message in the room, then leave.  Subject to
+   *                 the app's `allow_member_bulk_delete` gate and per-room
+   *                 OPERATOR check — a plain member gets 403 back. */
+  async leave(options?: { deleteMessages?: "none" | "mine" | "all" }): Promise<void> {
+    const mode = options?.deleteMessages ?? "none";
+    const query = mode === "none"
+      ? ""
+      : `?delete_messages=${encodeURIComponent(mode)}`;
     await this.http.request<void>(
-      "POST", `/api/v1/rooms/${this.roomId}/leave`,
+      "POST", `/api/v1/rooms/${this.roomId}/leave${query}`,
+    );
+  }
+
+  /** Delete every message YOU sent in this room.  Standalone version of
+   *  `leave({ deleteMessages: "mine" })` — useful when a user wants to
+   *  scrub their history without actually leaving.  Other members'
+   *  messages are untouched; broadcasts `messages_cleared_by_sender`
+   *  so connected clients hide the vanished ones locally.
+   *  No OPERATOR gate — you own your messages. */
+  async deleteMyMessages(): Promise<{ cleared: number }> {
+    const raw = await this.http.request<unknown>(
+      "DELETE", `/api/v1/rooms/${this.roomId}/messages/mine`,
     );
+    return parseBulkDeleteBySenderResult(raw);
   }
 
   /**
@@ -769,14 +739,10 @@ export class Room {
     cleared: number;
     upToMessageId: MessageIdStr | null;
   }> {
-    const raw = await this.http.request<{
-      cleared: number;
-      up_to_message_id: string | null;
-    }>("DELETE", `/api/v1/rooms/${this.roomId}/messages`);
-    return {
-      cleared: raw.cleared,
-      upToMessageId: raw.up_to_message_id,
-    };
+    const raw = await this.http.request<unknown>(
+      "DELETE", `/api/v1/rooms/${this.roomId}/messages`,
+    );
+    return parseBulkDeleteResult(raw);
   }
 
   async react(messageId: MessageIdStr, key: string): Promise<void> {
@@ -801,7 +767,7 @@ export class Room {
     // camelCase contract here so callers (and the demo's renderMessage)
     // don't see `undefined` on `messageId` / `senderId` / etc.
     const raw = await this.http.request<{
-      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+      items: unknown[]; next_cursor: string | null; has_more: boolean;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, {
       since: String(sinceMessageId), limit,
     });
@@ -824,7 +790,7 @@ export class Room {
     hasMore: boolean;
   }> {
     const raw = await this.http.request<{
-      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+      items: unknown[]; next_cursor: string | null; has_more: boolean;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, { limit });
     return {
       items: raw.items.map(toMessageOut),
@@ -845,7 +811,7 @@ export class Room {
     hasMore: boolean;
   }> {
     const raw = await this.http.request<{
-      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+      items: unknown[]; next_cursor: string | null; has_more: boolean;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, {
       before: beforeMessageId, limit,
     });
@@ -881,7 +847,7 @@ export class Room {
     };
     if (opts?.before) params.before = opts.before;
     const raw = await this.http.request<{
-      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+      items: unknown[]; next_cursor: string | null; has_more: boolean;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages/search`, undefined, params);
     return {
       items: raw.items.map(toMessageOut),
@@ -895,40 +861,11 @@ export class Room {
    *  `room.deleteAllMessages()`. Server gates by membership for non-public
    *  rooms, so the caller must already be a member to read this.
    */
-  async listMembers(): Promise<Array<{
-    userId: string;
-    nickname: string | null;
-    role: "OPERATOR" | "MEMBER" | "KICKED";
-    pushTrigger: "ALL" | "MENTION" | "OFF";
-    lastReadMessageId: MessageIdStr | null;
-    joinedAt: string;
-    /** Cluster-wide presence dot. `null` when the server didn't resolve it. */
-    isOnline: boolean | null;
-    /** Per-room mute expiry. `null` = not muted. A far-future sentinel
-     *  (year 9999) means the operator picked "indefinite" — clients
-     *  should render that as "무기한" instead of a real timestamp. */
-    mutedUntil: string | null;
-  }>> {
-    const raw = await this.http.request<Array<{
-      user_id: string;
-      nickname?: string | null;
-      role: "OPERATOR" | "MEMBER" | "KICKED";
-      push_trigger: "ALL" | "MENTION" | "OFF";
-      last_read_message_id: string | null;
-      joined_at: string;
-      is_online?: boolean | null;
-      muted_until?: string | null;
-    }>>("GET", `/api/v1/rooms/${this.roomId}/members`);
-    return raw.map((m) => ({
-      userId: m.user_id,
-      nickname: m.nickname ?? null,
-      role: m.role,
-      pushTrigger: m.push_trigger,
-      lastReadMessageId: m.last_read_message_id,
-      joinedAt: m.joined_at,
-      isOnline: m.is_online ?? null,
-      mutedUntil: m.muted_until ?? null,
-    }));
+  async listMembers(): Promise<RoomMemberOut[]> {
+    const raw = await this.http.request<unknown[]>(
+      "GET", `/api/v1/rooms/${this.roomId}/members`,
+    );
+    return raw.map((m) => parseRoomMemberOut(m));
   }
 
   // -------- mute --------
@@ -958,18 +895,10 @@ export class Room {
    *  newer than the caller's `read_watermark`, plus the room's
    *  `last_message_id` so the UI can show a "•" dot regardless of count. */
   async unread(): Promise<RoomUnread> {
-    const raw = await this.http.request<{
-      room_id: string;
-      unread_count: number;
-      last_read_message_id: string | null;
-      last_message_id: string | null;
-    }>("GET", `/api/v1/rooms/${this.roomId}/unread`);
-    return {
-      roomId: raw.room_id,
-      unreadCount: raw.unread_count,
-      lastReadMessageId: raw.last_read_message_id,
-      lastMessageId: raw.last_message_id,
-    };
+    const raw = await this.http.request<unknown>(
+      "GET", `/api/v1/rooms/${this.roomId}/unread`,
+    );
+    return parseRoomUnread(raw);
   }
 
   // -------- freeze --------
@@ -1007,80 +936,32 @@ export class Room {
   // -------- announcements --------
 
   async listAnnouncements(): Promise<Announcement[]> {
-    const raw = await this.http.request<Array<{
-      id: number;
-      room_id: string;
-      content: string;
-      created_by: string;
-      created_at: string;
-      updated_at: string;
-    }>>("GET", `/api/v1/rooms/${this.roomId}/announcements`);
-    return raw.map((a) => ({
-      id: a.id,
-      roomId: a.room_id,
-      content: a.content,
-      createdBy: a.created_by,
-      createdAt: a.created_at,
-      updatedAt: a.updated_at,
-    }));
+    const raw = await this.http.request<unknown[]>(
+      "GET", `/api/v1/rooms/${this.roomId}/announcements`,
+    );
+    return raw.map((a) => parseAnnouncementOut(a));
   }
 
   async getCurrentAnnouncement(): Promise<Announcement | null> {
-    const raw = await this.http.request<{
-      id: number;
-      room_id: string;
-      content: string;
-      created_by: string;
-      created_at: string;
-      updated_at: string;
-    } | null>("GET", `/api/v1/rooms/${this.roomId}/announcements/current`);
+    const raw = await this.http.request<unknown>(
+      "GET", `/api/v1/rooms/${this.roomId}/announcements/current`,
+    );
     if (!raw) return null;
-    return {
-      id: raw.id,
-      roomId: raw.room_id,
-      content: raw.content,
-      createdBy: raw.created_by,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at,
-    };
+    return parseAnnouncementOut(raw);
   }
 
   async postAnnouncement(content: string): Promise<Announcement> {
-    const raw = await this.http.request<{
-      id: number;
-      room_id: string;
-      content: string;
-      created_by: string;
-      created_at: string;
-      updated_at: string;
-    }>("POST", `/api/v1/rooms/${this.roomId}/announcements`, { content });
-    return {
-      id: raw.id,
-      roomId: raw.room_id,
-      content: raw.content,
-      createdBy: raw.created_by,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at,
-    };
+    const raw = await this.http.request<unknown>(
+      "POST", `/api/v1/rooms/${this.roomId}/announcements`, { content },
+    );
+    return parseAnnouncementOut(raw);
   }
 
   async updateAnnouncement(id: number, content: string): Promise<Announcement> {
-    const raw = await this.http.request<{
-      id: number;
-      room_id: string;
-      content: string;
-      created_by: string;
-      created_at: string;
-      updated_at: string;
-    }>("PATCH", `/api/v1/rooms/${this.roomId}/announcements/${id}`, { content });
-    return {
-      id: raw.id,
-      roomId: raw.room_id,
-      content: raw.content,
-      createdBy: raw.created_by,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at,
-    };
+    const raw = await this.http.request<unknown>(
+      "PATCH", `/api/v1/rooms/${this.roomId}/announcements/${id}`, { content },
+    );
+    return parseAnnouncementOut(raw);
   }
 
   async deleteAnnouncement(id: number): Promise<void> {
@@ -1111,51 +992,19 @@ export class Room {
     const body: Record<string, unknown> = {};
     if (opts && "expiresInHours" in opts) body.expires_in_hours = opts.expiresInHours;
     if (opts && "maxUses" in opts) body.max_uses = opts.maxUses;
-    const raw = await this.http.request<{
-      token: string;
-      room_id: string;
-      created_by: string;
-      created_at: string;
-      expires_at: string | null;
-      max_uses: number | null;
-      used_count: number;
-      revoked_at: string | null;
-    }>("POST", `/api/v1/rooms/${this.roomId}/invites`, body);
-    return {
-      token: raw.token,
-      roomId: raw.room_id,
-      createdBy: raw.created_by,
-      createdAt: raw.created_at,
-      expiresAt: raw.expires_at,
-      maxUses: raw.max_uses,
-      usedCount: raw.used_count,
-      revokedAt: raw.revoked_at,
-    };
+    const raw = await this.http.request<unknown>(
+      "POST", `/api/v1/rooms/${this.roomId}/invites`, body,
+    );
+    return parseInviteTokenOut(raw);
   }
 
   /** OPERATOR-only: list all invite tokens for this room (including
    *  revoked / expired / exhausted), newest first. */
   async listInvites(): Promise<InviteToken[]> {
-    const raw = await this.http.request<Array<{
-      token: string;
-      room_id: string;
-      created_by: string;
-      created_at: string;
-      expires_at: string | null;
-      max_uses: number | null;
-      used_count: number;
-      revoked_at: string | null;
-    }>>("GET", `/api/v1/rooms/${this.roomId}/invites`);
-    return raw.map((r) => ({
-      token: r.token,
-      roomId: r.room_id,
-      createdBy: r.created_by,
-      createdAt: r.created_at,
-      expiresAt: r.expires_at,
-      maxUses: r.max_uses,
-      usedCount: r.used_count,
-      revokedAt: r.revoked_at,
-    }));
+    const raw = await this.http.request<unknown[]>(
+      "GET", `/api/v1/rooms/${this.roomId}/invites`,
+    );
+    return raw.map((r) => parseInviteTokenOut(r));
   }
 
   /** OPERATOR-only: revoke a token immediately. Idempotent — revoking
@@ -1167,6 +1016,87 @@ export class Room {
     );
   }
 
+  // -------- join requests --------
+
+  /**
+   * Ask to join this room (self). Behavior depends on the room's
+   * `joinPolicy`:
+   *   - `OPEN` → the caller is added immediately (`status: "joined"`);
+   *   - `APPROVAL_REQUIRED` → the request lands in the operators' inbox
+   *     (`status: "pending"`) until [`approveJoinRequest`] / reject.
+   * Idempotent for members (`status: "already_member"`).
+   *
+   * @param reason Optional note shown to operators ("하은이 반 친구 엄마예요").
+   */
+  async requestJoin(reason?: string): Promise<JoinRequestCreateResponse> {
+    const raw = await this.http.request<unknown>(
+      "POST", `/api/v1/rooms/${this.roomId}/join-request`,
+      reason ? { reason } : {},
+    );
+    return parseJoinRequestCreateResponse(raw);
+  }
+
+  /** Cancel the caller's own pending join request. */
+  async cancelJoinRequest(): Promise<void> {
+    await this.http.request<void>(
+      "DELETE", `/api/v1/rooms/${this.roomId}/join-request`,
+    );
+  }
+
+  /** OPERATOR-only: list join requests for this room (the approval inbox).
+   *  Defaults to pending only — pass a status to see processed history. */
+  async listJoinRequests(opts?: {
+    status?: "PENDING" | "APPROVED" | "REJECTED" | "CANCELLED";
+    limit?: number;
+    offset?: number;
+  }): Promise<JoinRequestListResponse> {
+    const raw = await this.http.request<unknown>(
+      "GET", `/api/v1/rooms/${this.roomId}/join-requests`, undefined, {
+        ...(opts?.status ? { status: opts.status } : {}),
+        ...(opts?.limit !== undefined ? { limit: opts.limit } : {}),
+        ...(opts?.offset !== undefined ? { offset: opts.offset } : {}),
+      },
+    );
+    return parseJoinRequestListResponse(raw);
+  }
+
+  /** OPERATOR-only: approve a pending join request — the requester becomes
+   *  a MEMBER. [reason] is echoed back to them in later list calls. */
+  async approveJoinRequest(userId: string, reason?: string): Promise<void> {
+    await this.http.request<void>(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/join-requests/${encodeURIComponent(userId)}/approve`,
+      reason ? { reason } : {},
+    );
+  }
+
+  /** OPERATOR-only: reject a pending join request. */
+  async rejectJoinRequest(userId: string, reason?: string): Promise<void> {
+    await this.http.request<void>(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/join-requests/${encodeURIComponent(userId)}/reject`,
+      reason ? { reason } : {},
+    );
+  }
+
+  // -------- hide / unhide --------
+
+  /** Hide this room from the caller's own room list (self, reversible —
+   *  the KakaoTalk "숨기기"). The room typically reappears via [unhide]
+   *  or on new activity, per server policy. Messages are untouched. */
+  async hide(): Promise<void> {
+    await this.http.request<void>(
+      "POST", `/api/v1/rooms/${this.roomId}/hide`,
+    );
+  }
+
+  /** Undo [hide] — the room shows up in the caller's list again. */
+  async unhide(): Promise<void> {
+    await this.http.request<void>(
+      "POST", `/api/v1/rooms/${this.roomId}/unhide`,
+    );
+  }
+
   // -------- internal dispatch --------
 
   on<K extends keyof RoomEvents>(event: K, fn: (p: RoomEvents[K]) => void): () => void {