@kakao-bot/sdk 0.4.0 → 0.5.0

package/README.md

@@ -45,7 +45,13 @@ await kakao.sendMessage({
 });
 ```
 
-방에 누가 있는지는 `listRoomMembers`로 봅니다(`rooms:read` 권한). 카톡 방 정보에서 온 계정 ID와, 그 방에서 본 적 있는 표시 이름을 돌려줍니다.
+이름만 알면 `mentions`로 태그할 수 있습니다. 그 방 참여자 한 명으로 정해져야 보내고, 없거나 여럿이면 `KakaoApiError`(`mention_name_unknown` / `mention_name_ambiguous`, `body.candidates`)로 거절됩니다.
+
+```ts
+await bot.sendMessage({ roomSlug: "tf", text: "@이현근 확인 부탁해요", mentions: ["이현근"] });
+```
+
+방에 누가 있는지는 `listRoomMembers`(목록만) 또는 `getRoomMembers`(검색 `q`, 인원 `known`/`total`, 오픈채팅 여부, 마지막 동기화)로 봅니다(`rooms:read` 권한). 카톡 방 정보에서 온 계정 ID와, 그 방에서 본 적 있는 표시 이름을 돌려줍니다.
 
 ```ts
 const members = await bot.listRoomMembers({ roomSlug: "tf" });

package/dist/index.d.ts

@@ -31,6 +31,12 @@ export type SendMessageInput = ({
     text: string;
     /** Reuse this ID for the same logical send. No automatic retries are performed. */
     requestId?: string;
+    /**
+     * Tag people by display name (e.g. `["이현근"]`). Each must match exactly one room member;
+     * `@이름` in `text` becomes the tag, otherwise tags go first. Unknown or ambiguous names
+     * reject with `mention_name_unknown` / `mention_name_ambiguous` (and `candidates`), unsent.
+     */
+    mentions?: string[];
 };
 export interface SendMessageResult {
     ok: true;
@@ -57,6 +63,18 @@ export interface RoomMember {
     /** `<@userId>`; tags the member when included in message text. */
     mention: string;
 }
+/** A room's members plus how complete the list is. */
+export interface RoomMembers {
+    members: RoomMember[];
+    /** Members the hub knows. */
+    known: number;
+    /** KakaoTalk's own member count, when reported. */
+    total: number | null;
+    /** Open chat. Full lists come from Kakao's server hourly; `total` may briefly exceed `known`. */
+    openChat: boolean;
+    /** Last full member sync (epoch ms), or null before the first one. */
+    syncedAt: number | null;
+}
 /** Hub-signed inbound webhook. Validate the HMAC on the raw body before parsing. */
 export interface InboundWebhookEvent {
     event_id: string;
@@ -95,5 +113,16 @@ export declare class KakaoBot {
     } | {
         roomSlug: string;
     }, options?: RequestOptions): Promise<RoomMember[]>;
+    /**
+     * Members with list completeness (`known`, `total`, `openChat`, `syncedAt`). `q` filters by
+     * name (case-insensitive substring) or exact user ID. Requires the `rooms:read` scope.
+     */
+    getRoomMembers(room: ({
+        roomId: string;
+    } | {
+        roomSlug: string;
+    }) & {
+        q?: string;
+    }, options?: RequestOptions): Promise<RoomMembers>;
     private request;
 }

package/dist/index.js

@@ -53,7 +53,12 @@ export class KakaoBot {
             ? `/v1/rooms/id/${encodeURIComponent(input.roomId)}/messages`
             : input.roomSlug !== undefined
                 ? `/v1/rooms/${encodeURIComponent(input.roomSlug)}/messages`
-                : "/v1/messages", "POST", { room: input.room, msg: input.text, request_id: requestId }, options.signal, requestId);
+                : "/v1/messages", "POST", {
+            room: input.room,
+            msg: input.text,
+            request_id: requestId,
+            ...(input.mentions ? { mentions: input.mentions } : {}),
+        }, options.signal, requestId);
         if (!object(data) ||
             data.ok !== true ||
             typeof data.queued !== "boolean" ||
@@ -79,9 +84,17 @@ export class KakaoBot {
     }
     /** Members of a room bound to this service. Requires the `rooms:read` scope. */
     async listRoomMembers(room, options = {}) {
-        const path = "roomId" in room
+        return (await this.getRoomMembers(room, options)).members;
+    }
+    /**
+     * Members with list completeness (`known`, `total`, `openChat`, `syncedAt`). `q` filters by
+     * name (case-insensitive substring) or exact user ID. Requires the `rooms:read` scope.
+     */
+    async getRoomMembers(room, options = {}) {
+        const base = "roomId" in room
             ? `/v1/rooms/id/${encodeURIComponent(room.roomId)}/members`
             : `/v1/rooms/${encodeURIComponent(room.roomSlug)}/members`;
+        const path = room.q ? `${base}?q=${encodeURIComponent(room.q)}` : base;
         const data = await this.request(path, "GET", undefined, options.signal);
         if (!object(data) ||
             !Array.isArray(data.members) ||
@@ -91,7 +104,13 @@ export class KakaoBot {
                 (member.name === null || typeof member.name === "string") &&
                 member.mention === `<@${member.userId}>`))
             throw new KakaoProtocolError();
-        return data.members;
+        return {
+            members: data.members,
+            known: typeof data.known === "number" ? data.known : data.members.length,
+            total: typeof data.total === "number" ? data.total : null,
+            openChat: data.openChat === true,
+            syncedAt: typeof data.syncedAt === "number" ? data.syncedAt : null,
+        };
     }
     async request(path, method, body, signal, requestId) {
         const timeout = AbortSignal.timeout(this.timeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kakao-bot/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Typed server-side client for the Kakao Bot Hub API",
   "license": "MIT",
   "author": "Jeongmin Lee",