connectbase-client 6.6.1 → 6.7.0

package/dist/index.d.mts

@@ -161,7 +161,7 @@ declare class GameError extends Error {
  * | `quota_exceeded` | 월간 WebSocket 사용 시간 소진 | 불가 | 플랜 업그레이드 전까지 재시도 무의미 |
  * | `server_at_capacity` | 서버 일시 혼잡 | 가능 | 잠시 후 재시도 |
  * | `rate_limited` | 한 IP 에서 연결 시도가 너무 잦음 (6.6.0+) | 가능 | `connect()` 가 `retryAfterMs` 만큼(지터 포함) 기다렸다 스스로 다시 붙는다. 연결 제한 시간 안에 못 붙으면 이 에러를 던진다 |
- * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | 잠시 후 재시도 |
+ * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | `connect()` 가 `retryAfterMs` 만큼(없으면 지수 백오프) 기다렸다 스스로 다시 붙는다 (6.7.0+). 연결 제한 시간 안에 못 붙으면 이 에러를 던진다 |
  * | `unauthorized` | 공개 키/액세스 토큰이 유효하지 않음 | 불가 | 키·토큰 확인 (토큰 만료면 새 토큰으로 `connect()`) |
  * | `forbidden` | 다른 앱의 경로로 접속 | 불가 | 설정 확인 |
  * | `invalid_user_id` | 공개 키 연결에 UUID 형식 `userId` | 불가 | `accessToken` 을 쓰거나 UUID 가 아닌 식별자 사용 |
@@ -177,8 +177,10 @@ type RealtimeConnectionErrorCode = "connection_limit_exceeded" | "quota_exceeded
  * 연결을 받은 뒤 거부 이유를 보내고 4000+HTTP상태 close 코드(예: 4401, 4402, 4503)로 닫는다.
  *
  * - 거부는 SSE 폴백 대상이 아니다 — 네트워크는 정상이고 서버가 받지 않은 것이다.
- * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: `rate_limited`)는 `connect()` 가 연결 제한
- *   시간(`timeout`) 안에서 그 시각에 지터를 더해 스스로 다시 시도한다. 그 밖의 거부는 바로 던진다.
+ * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: `rate_limited`, `auth_unavailable`)는 `connect()` 가
+ *   연결 제한 시간(`timeout`) 안에서 그 시각에 지터를 더해 스스로 다시 시도한다. `rate_limited` 와
+ *   `auth_unavailable` 은 시각이 없어도(구버전 서버) 지수 백오프로 다시 시도한다(6.7.0+). 그 밖의 거부
+ *   (`unauthorized`, `connection_limit_exceeded` 등)는 바로 던진다.
  * - 자동 재연결 중에 받은 거부는 `retryable` 이면 백오프로 계속 시도하고, 아니면 재연결을 멈추고
  *   `cb.realtime.onError` 로 이 에러를 알린다.
  *
@@ -204,8 +206,8 @@ declare class RealtimeConnectionError extends Error {
     /** 거부 상세 (예: connection_limit_exceeded 의 `current`/`limit`, quota_exceeded 의 `quota`/`unit`). */
     details?: Record<string, unknown>;
     /**
-     * 서버가 알려 준, 다시 시도해도 되는 시각까지의 대기(ms). 언제 풀리는지 서버가 정확히 아는 거부
-     * (`rate_limited`)에만 있다.
+     * 서버가 알려 준, 다시 시도해도 되는 시각까지의 대기(ms). 서버가 재시도 시각을 정해 주는 거부
+     * (`rate_limited`, 그리고 6.7.0 과 함께 배포된 서버의 `auth_unavailable`)에만 있다.
      */
     retryAfterMs?: number;
     constructor(init: {
@@ -232,9 +234,9 @@ declare class RealtimeConnectionError extends Error {
  * | `RATE_LIMITED` | 카테고리 또는 연결의 초당 메시지 한도 초과 |
  * | `MESSAGE_TOO_LARGE` | 카테고리 최대 메시지 크기 초과 |
  * | `QUOTA_EXCEEDED` | 플랜 할당량 초과 |
- * | `CATEGORY_NOT_FOUND` | 카테고리가 없거나 비활성 |
+ * | `CATEGORY_NOT_FOUND` | 카테고리가 없거나 비활성 (채널 이름 규칙에 어긋난 문자열 채널도 이 코드로 온다) |
  * | `MAX_SUBSCRIBERS_REACHED` | 카테고리 최대 구독자 수 도달 |
- * | `ROOM_ACCESS_DENIED` | room 인가 함수가 거부했다 |
+ * | `ROOM_ACCESS_DENIED` | room 인가 함수가 거부했다 (함수가 없거나, 실패하거나, 10초 안에 답하지 않아도 거부로 처리된다) |
  *
  * ```ts
  * try {
@@ -607,7 +609,12 @@ declare class HttpClient {
      * 먼저 보내 Cloudflare 를 두 번 왕복하고, 앱의 "로컬 개발 origin 허용" 이 꺼진 localhost 페이지에서는
      * 키 기반 opt-in 에 막혀 브라우저만 direct 를 못 썼다(Node 는 썼다 — platform-issue 01a15e24).
      * 서버는 이 경로를 키 없이 열어 두고 같은 값을 본문으로도 준다. 본문을 읽으므로 CORS
-     * Expose-Headers 에도 기대지 않는다. 실패는 조용히 무시한다 — direct 는 최적화일 뿐이다.
+     * Expose-Headers 에도 기대지 않는다. 실패는 호출자에게 던지고 호출자(RealtimeAPI)가 조용히 넘어간다 —
+     * direct 는 최적화일 뿐이다.
+     *
+     * 조회 자체는 같은 baseUrl 의 인스턴스끼리 함께 쓴다(6.7.0+, {@link sharedEdgeHints} 참고). 진행 중인
+     * 조회가 있으면 새로 보내지 않고 기다리며, 성공한 결과는 잠시 다시 쓴다. 받아들일지는 이 인스턴스가 정한다 —
+     * 이미 배웠거나(`directRealtimeBaseUrl`) direct 를 포기했으면(`directRealtimeDisabled`) 바꾸지 않는다.
      */
     primeEdgeHints(timeoutMs: number): Promise<void>;
     /**
@@ -2160,17 +2167,28 @@ declare class AuthAPI {
      *     role: 'editor',
      *     custom_data: { level: 5 }
      * })
+     *
+     * // 역할 여러 개 (6.7.0+): role 은 주 역할(RLS auth.role), roles 는 추가 역할 목록을 **통째로 바꾼다**
+     * // ([] 면 비우고, 빼면 그대로). auth.roles, hasRole(), 실시간 publisher_roles 는 role + roles 를 함께 본다.
+     * await cb.auth.adminUpdateMember('member-uuid', { roles: ['performer'] })
+     * // → { role: 'admin', roles: ['performer'], effective_roles: ['admin', 'performer'], ... }
      * ```
      */
     adminUpdateMember(memberID: string, fields: {
         nickname?: string;
         role?: string;
+        /** 추가 역할 목록 — 보내면 통째로 바뀐다(빈 배열이면 비운다). 각 64바이트 이하, role 포함 16개 이하. */
+        roles?: string[];
         custom_data?: Record<string, unknown>;
     }): Promise<{
         member_id: string;
         nickname: string;
         custom_data: Record<string, unknown>;
         role: string;
+        /** 추가 역할 목록 (6.7.0+ 서버) */
+        roles?: string[];
+        /** role + roles (중복 제거, role 이 먼저). RLS auth.roles 와 실시간 publisher_roles 가 보는 값 (6.7.0+ 서버) */
+        effective_roles?: string[];
     }>;
     /**
      * Admin: 다른 멤버를 삭제(탈퇴 처리)합니다. **되돌릴 수 없습니다.**
@@ -7951,6 +7969,20 @@ declare class QueueAPI {
 interface SubscribeOptions {
     /** 히스토리 로드 개수 (persist=true인 카테고리만) */
     historyLimit?: number;
+    /**
+     * 카테고리 안의 room 하나를 구독한다 (6.7.0+, platform-issue 01a15e81). 서버로 가는 채널 이름은
+     * `${category}:${room}` 이다 — `subscribe('concert', { room: 'show-1025' })` 는 `concert:show-1025` 를
+     * 구독한다. 설정(발행 정책, 방송인 역할, persist 등)은 베이스 카테고리(`concert`)의 것을 쓰고, 메시지는
+     * 같은 room 을 구독한 연결끼리만 오간다. 문자열로 `subscribe('concert:show-1025')` 라고 써도 같다.
+     *
+     * - 영문, 숫자, `-`, `_`, `.` 로 1~128자여야 하고, 이때 `category` 는 영문, 숫자, `-`, `_` 만 쓴
+     *   베이스 카테고리 이름이어야 한다(서버의 채널 규칙). 어긋나면 서버에 보내기 전에 에러를 던진다 —
+     *   서버는 잘못된 채널을 `CATEGORY_NOT_FOUND` 로만 알려 원인이 보이지 않는다.
+     * - 카테고리가 `require_room_auth` 이면 서버가 앱의 room 인가 함수를 불러 구독을 허락받는다. 함수가
+     *   `{ authorized: true, publisher: true }` 를 돌려주면 이 연결(로그인 멤버)은 그 room 의 방송인이 된다
+     *   (`info.isPublisher`, 받는 쪽의 `fromPublisher`).
+     */
+    room?: string;
 }
 /**
  * 카테고리 발행 정책 (6.6.0+). 콘솔이나 API 로 카테고리에 설정한다.
@@ -7962,6 +7994,7 @@ interface SubscribeOptions {
 type RealtimeSendPolicy = "open" | "upstream" | "publishers_only";
 /** 카테고리 정보 */
 interface CategoryInfo {
+    /** 구독한 채널 이름 (서버가 돌려준 값). room 을 구독했으면 `category:room` 이다. */
     category: string;
     persist: boolean;
     historyCount: number;
@@ -7969,6 +8002,7 @@ interface CategoryInfo {
     /**
      * 이 연결이 이 카테고리의 방송인인지 (6.6.0+). 카테고리 `publisher_roles` 의 역할을 가진
      * **로그인 멤버(accessToken) 연결**만 방송인이다 — 공개 키(익명) 연결은 항상 `false`.
+     * room 채널은 room 인가 함수가 `publisher: true` 를 돌려준 로그인 멤버도 그 room 의 방송인이다 (6.7.0+).
      * 구독할 때 정해지므로 역할이나 카테고리 설정이 바뀌면 다시 구독해야 반영된다.
      */
     isPublisher: boolean;
@@ -7978,13 +8012,27 @@ interface CategoryInfo {
 /** 메시지 데이터 */
 interface RealtimeMessage<T = unknown> {
     id?: string;
+    /** 메시지가 온 채널 이름. room 채널이면 `category:room` 이다. */
     category: string;
+    /**
+     * 보낸 연결의 클라이언트 ID(접속할 때 `client_id` 로 보내는 값). **클라이언트가 정해서 보내는 값이라
+     * 누구나 다른 값을 흉내 낼 수 있다** — 화면 표시나 내 메시지 구분 정도에만 쓰고, 누가 보냈는지
+     * 믿어야 하는 판단(권한, 점수, 신고)에는 {@link RealtimeMessage.fromMember} 를 쓴다.
+     */
     from?: string;
+    /**
+     * 보낸 사람의 앱 멤버 ID — 서버가 검증한 값이다 (6.7.0+, platform-issue 01a15e86). 보낸 연결이
+     * 앱 멤버 `accessToken` 으로 접속했을 때만 있고, 공개 키(익명) 연결이 보낸 메시지에는 없다.
+     * `from` 이나 `data` 안의 값과 달리 클라이언트가 위조할 수 없다. 실시간 메시지와 히스토리 모두에
+     * 실린다(구버전 서버는 보내지 않는다).
+     */
+    fromMember?: string;
     data: T;
     sentAt: number;
     /**
-     * 보낸 연결이 이 카테고리의 방송인이라는 **서버 보증** (6.6.0+). `data` 안의 값과 달리 클라이언트가
-     * 위조할 수 없다 — 방송인 메시지만 골라 처리할 때 이 값으로 가린다. 히스토리 메시지에는 없다.
+     * 보낸 연결이 이 카테고리(room 채널이면 그 room)의 방송인이라는 **서버 보증** (6.6.0+). `data` 안의
+     * 값과 달리 클라이언트가 위조할 수 없다 — 방송인 메시지만 골라 처리할 때 이 값으로 가린다.
+     * 히스토리 메시지에는 없다.
      */
     fromPublisher?: boolean;
 }
@@ -8045,6 +8093,17 @@ interface SendOptions {
 interface Subscription {
     /** 카테고리 정보 */
     info: CategoryInfo;
+    /**
+     * 서버에 구독한 채널 이름 (6.7.0+). room 을 구독했으면 `category:room`, 아니면 카테고리 이름이다.
+     * `realtime.unsubscribe()`, `realtime.markRead()`, `realtime.onReadReceipt()` 처럼 이름을 받는
+     * 메서드에는 이 값을 넘긴다.
+     */
+    readonly channel: string;
+    /**
+     * 구독한 room (6.7.0+). `subscribe(category, { room })` 이나 `subscribe('category:room')` 으로
+     * 구독했을 때만 있다.
+     */
+    readonly room?: string;
     /** 메시지 전송 */
     send<T = unknown>(data: T, options?: SendOptions): Promise<void>;
     /** 히스토리 조회 (persist=true인 경우만) */
@@ -8299,21 +8358,35 @@ declare class RealtimeAPI {
     disconnect(): void;
     /**
      * 카테고리 구독
+     *
+     * `options.room` 을 주면 그 카테고리의 room 하나를 구독한다 (6.7.0+). 서버 채널 이름은
+     * `${category}:${room}` 이고, 구독 객체의 `send` / `getHistory` / `unsubscribe` / `onMessage`, 재연결 뒤
+     * 다시 구독하기는 모두 이 채널 이름으로 동작한다(`subscription.channel`).
+     *
+     * @example
+     * ```typescript
+     * const stage = await client.realtime.subscribe('concert', { room: 'show-1025' })
+     * stage.channel          // 'concert:show-1025'
+     * stage.room             // 'show-1025'
+     * stage.info.isPublisher // room 인가 함수가 publisher: true 를 돌려준 로그인 멤버면 true
+     * ```
      */
     subscribe(category: string, options?: SubscribeOptions): Promise<Subscription>;
     /**
      * 구독 해제
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      */
     unsubscribe(category: string): Promise<void>;
     /**
      * 메시지 전송
-     * @param category 카테고리 이름
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      * @param data 전송할 데이터
      * @param options 전송 옵션 (includeSelf: 발신자도 메시지 수신 여부, 기본값 true)
      */
     sendMessage<T = unknown>(category: string, data: T, options?: SendOptions): Promise<void>;
     /**
      * 히스토리 조회
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      */
     getHistory<T = unknown>(category: string, limit?: number): Promise<HistoryResponse<T>>;
     /**
@@ -8562,18 +8635,25 @@ declare class RealtimeAPI {
      * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
      * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
      * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
-     * 세션당 한 번만 묻는다.
+     * 인스턴스당 한 번만 묻고, 같은 baseUrl 의 인스턴스끼리는 진행 중인 조회와 배운 결과를 함께 쓴다
+     * (6.7.0+, HttpClient.primeEdgeHints 참고 — 한 페이지의 인스턴스 10개가 동시에 물어 대부분 1.5초를 넘기던
+     * platform-issue 01a15e81).
      */
     private primeDirectRealtime;
     /**
      * 첫 연결을 연결 제한 시간(`timeout`) 안에서 다시 시도한다 (6.6.0+, platform-issue 01a15e24).
      *
-     * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`):
-     *   그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때 앱이 재시도를 짜지 않아도 된다.
+     * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`, 인증 서버가
+     *   잠깐 닿지 않는 `auth_unavailable`): 그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때
+     *   앱이 재시도를 짜지 않아도 된다.
+     * - `rate_limited` / `auth_unavailable` 인데 재시도 시각이 없으면(사유 프레임 없이 close 코드만 왔거나 구버전
+     *   서버) 지수 백오프로 다시 한다. `auth_unavailable` 은 6.6.0 까지 바로 던져, 인증 서버가 몇 초 흔들리는
+     *   동안 들어온 관객이 전부 연결에 실패했다(6.7.0, platform-issue 01a15e81).
      * - 이유 없는 핸드셰이크 실패: 두 번까지 백오프 후 다시 한다. 네트워크가 WebSocket 을 실제로 막으면
      *   매번 실패하고, 앞단의 일시 거부는 다시 하면 붙는다 — 한 번 실패로 SSE 폴백하던 것이 연결 속도
      *   제한을 "네트워크 차단" 으로 오진한 원인이었다.
-     * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다.
+     * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다. 다시 시도할 시간이 남지 않아도
+     *   마지막 거부를 그대로 던진다(`retryAfterMs` 가 있으면 앱이 그 시각에 다시 부를 수 있다).
      */
     private connectWithRetry;
     private doConnect;

package/dist/index.d.ts

@@ -161,7 +161,7 @@ declare class GameError extends Error {
  * | `quota_exceeded` | 월간 WebSocket 사용 시간 소진 | 불가 | 플랜 업그레이드 전까지 재시도 무의미 |
  * | `server_at_capacity` | 서버 일시 혼잡 | 가능 | 잠시 후 재시도 |
  * | `rate_limited` | 한 IP 에서 연결 시도가 너무 잦음 (6.6.0+) | 가능 | `connect()` 가 `retryAfterMs` 만큼(지터 포함) 기다렸다 스스로 다시 붙는다. 연결 제한 시간 안에 못 붙으면 이 에러를 던진다 |
- * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | 잠시 후 재시도 |
+ * | `auth_unavailable` | 인증 서버 일시 장애 | 가능 | `connect()` 가 `retryAfterMs` 만큼(없으면 지수 백오프) 기다렸다 스스로 다시 붙는다 (6.7.0+). 연결 제한 시간 안에 못 붙으면 이 에러를 던진다 |
  * | `unauthorized` | 공개 키/액세스 토큰이 유효하지 않음 | 불가 | 키·토큰 확인 (토큰 만료면 새 토큰으로 `connect()`) |
  * | `forbidden` | 다른 앱의 경로로 접속 | 불가 | 설정 확인 |
  * | `invalid_user_id` | 공개 키 연결에 UUID 형식 `userId` | 불가 | `accessToken` 을 쓰거나 UUID 가 아닌 식별자 사용 |
@@ -177,8 +177,10 @@ type RealtimeConnectionErrorCode = "connection_limit_exceeded" | "quota_exceeded
  * 연결을 받은 뒤 거부 이유를 보내고 4000+HTTP상태 close 코드(예: 4401, 4402, 4503)로 닫는다.
  *
  * - 거부는 SSE 폴백 대상이 아니다 — 네트워크는 정상이고 서버가 받지 않은 것이다.
- * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: `rate_limited`)는 `connect()` 가 연결 제한
- *   시간(`timeout`) 안에서 그 시각에 지터를 더해 스스로 다시 시도한다. 그 밖의 거부는 바로 던진다.
+ * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: `rate_limited`, `auth_unavailable`)는 `connect()` 가
+ *   연결 제한 시간(`timeout`) 안에서 그 시각에 지터를 더해 스스로 다시 시도한다. `rate_limited` 와
+ *   `auth_unavailable` 은 시각이 없어도(구버전 서버) 지수 백오프로 다시 시도한다(6.7.0+). 그 밖의 거부
+ *   (`unauthorized`, `connection_limit_exceeded` 등)는 바로 던진다.
  * - 자동 재연결 중에 받은 거부는 `retryable` 이면 백오프로 계속 시도하고, 아니면 재연결을 멈추고
  *   `cb.realtime.onError` 로 이 에러를 알린다.
  *
@@ -204,8 +206,8 @@ declare class RealtimeConnectionError extends Error {
     /** 거부 상세 (예: connection_limit_exceeded 의 `current`/`limit`, quota_exceeded 의 `quota`/`unit`). */
     details?: Record<string, unknown>;
     /**
-     * 서버가 알려 준, 다시 시도해도 되는 시각까지의 대기(ms). 언제 풀리는지 서버가 정확히 아는 거부
-     * (`rate_limited`)에만 있다.
+     * 서버가 알려 준, 다시 시도해도 되는 시각까지의 대기(ms). 서버가 재시도 시각을 정해 주는 거부
+     * (`rate_limited`, 그리고 6.7.0 과 함께 배포된 서버의 `auth_unavailable`)에만 있다.
      */
     retryAfterMs?: number;
     constructor(init: {
@@ -232,9 +234,9 @@ declare class RealtimeConnectionError extends Error {
  * | `RATE_LIMITED` | 카테고리 또는 연결의 초당 메시지 한도 초과 |
  * | `MESSAGE_TOO_LARGE` | 카테고리 최대 메시지 크기 초과 |
  * | `QUOTA_EXCEEDED` | 플랜 할당량 초과 |
- * | `CATEGORY_NOT_FOUND` | 카테고리가 없거나 비활성 |
+ * | `CATEGORY_NOT_FOUND` | 카테고리가 없거나 비활성 (채널 이름 규칙에 어긋난 문자열 채널도 이 코드로 온다) |
  * | `MAX_SUBSCRIBERS_REACHED` | 카테고리 최대 구독자 수 도달 |
- * | `ROOM_ACCESS_DENIED` | room 인가 함수가 거부했다 |
+ * | `ROOM_ACCESS_DENIED` | room 인가 함수가 거부했다 (함수가 없거나, 실패하거나, 10초 안에 답하지 않아도 거부로 처리된다) |
  *
  * ```ts
  * try {
@@ -607,7 +609,12 @@ declare class HttpClient {
      * 먼저 보내 Cloudflare 를 두 번 왕복하고, 앱의 "로컬 개발 origin 허용" 이 꺼진 localhost 페이지에서는
      * 키 기반 opt-in 에 막혀 브라우저만 direct 를 못 썼다(Node 는 썼다 — platform-issue 01a15e24).
      * 서버는 이 경로를 키 없이 열어 두고 같은 값을 본문으로도 준다. 본문을 읽으므로 CORS
-     * Expose-Headers 에도 기대지 않는다. 실패는 조용히 무시한다 — direct 는 최적화일 뿐이다.
+     * Expose-Headers 에도 기대지 않는다. 실패는 호출자에게 던지고 호출자(RealtimeAPI)가 조용히 넘어간다 —
+     * direct 는 최적화일 뿐이다.
+     *
+     * 조회 자체는 같은 baseUrl 의 인스턴스끼리 함께 쓴다(6.7.0+, {@link sharedEdgeHints} 참고). 진행 중인
+     * 조회가 있으면 새로 보내지 않고 기다리며, 성공한 결과는 잠시 다시 쓴다. 받아들일지는 이 인스턴스가 정한다 —
+     * 이미 배웠거나(`directRealtimeBaseUrl`) direct 를 포기했으면(`directRealtimeDisabled`) 바꾸지 않는다.
      */
     primeEdgeHints(timeoutMs: number): Promise<void>;
     /**
@@ -2160,17 +2167,28 @@ declare class AuthAPI {
      *     role: 'editor',
      *     custom_data: { level: 5 }
      * })
+     *
+     * // 역할 여러 개 (6.7.0+): role 은 주 역할(RLS auth.role), roles 는 추가 역할 목록을 **통째로 바꾼다**
+     * // ([] 면 비우고, 빼면 그대로). auth.roles, hasRole(), 실시간 publisher_roles 는 role + roles 를 함께 본다.
+     * await cb.auth.adminUpdateMember('member-uuid', { roles: ['performer'] })
+     * // → { role: 'admin', roles: ['performer'], effective_roles: ['admin', 'performer'], ... }
      * ```
      */
     adminUpdateMember(memberID: string, fields: {
         nickname?: string;
         role?: string;
+        /** 추가 역할 목록 — 보내면 통째로 바뀐다(빈 배열이면 비운다). 각 64바이트 이하, role 포함 16개 이하. */
+        roles?: string[];
         custom_data?: Record<string, unknown>;
     }): Promise<{
         member_id: string;
         nickname: string;
         custom_data: Record<string, unknown>;
         role: string;
+        /** 추가 역할 목록 (6.7.0+ 서버) */
+        roles?: string[];
+        /** role + roles (중복 제거, role 이 먼저). RLS auth.roles 와 실시간 publisher_roles 가 보는 값 (6.7.0+ 서버) */
+        effective_roles?: string[];
     }>;
     /**
      * Admin: 다른 멤버를 삭제(탈퇴 처리)합니다. **되돌릴 수 없습니다.**
@@ -7951,6 +7969,20 @@ declare class QueueAPI {
 interface SubscribeOptions {
     /** 히스토리 로드 개수 (persist=true인 카테고리만) */
     historyLimit?: number;
+    /**
+     * 카테고리 안의 room 하나를 구독한다 (6.7.0+, platform-issue 01a15e81). 서버로 가는 채널 이름은
+     * `${category}:${room}` 이다 — `subscribe('concert', { room: 'show-1025' })` 는 `concert:show-1025` 를
+     * 구독한다. 설정(발행 정책, 방송인 역할, persist 등)은 베이스 카테고리(`concert`)의 것을 쓰고, 메시지는
+     * 같은 room 을 구독한 연결끼리만 오간다. 문자열로 `subscribe('concert:show-1025')` 라고 써도 같다.
+     *
+     * - 영문, 숫자, `-`, `_`, `.` 로 1~128자여야 하고, 이때 `category` 는 영문, 숫자, `-`, `_` 만 쓴
+     *   베이스 카테고리 이름이어야 한다(서버의 채널 규칙). 어긋나면 서버에 보내기 전에 에러를 던진다 —
+     *   서버는 잘못된 채널을 `CATEGORY_NOT_FOUND` 로만 알려 원인이 보이지 않는다.
+     * - 카테고리가 `require_room_auth` 이면 서버가 앱의 room 인가 함수를 불러 구독을 허락받는다. 함수가
+     *   `{ authorized: true, publisher: true }` 를 돌려주면 이 연결(로그인 멤버)은 그 room 의 방송인이 된다
+     *   (`info.isPublisher`, 받는 쪽의 `fromPublisher`).
+     */
+    room?: string;
 }
 /**
  * 카테고리 발행 정책 (6.6.0+). 콘솔이나 API 로 카테고리에 설정한다.
@@ -7962,6 +7994,7 @@ interface SubscribeOptions {
 type RealtimeSendPolicy = "open" | "upstream" | "publishers_only";
 /** 카테고리 정보 */
 interface CategoryInfo {
+    /** 구독한 채널 이름 (서버가 돌려준 값). room 을 구독했으면 `category:room` 이다. */
     category: string;
     persist: boolean;
     historyCount: number;
@@ -7969,6 +8002,7 @@ interface CategoryInfo {
     /**
      * 이 연결이 이 카테고리의 방송인인지 (6.6.0+). 카테고리 `publisher_roles` 의 역할을 가진
      * **로그인 멤버(accessToken) 연결**만 방송인이다 — 공개 키(익명) 연결은 항상 `false`.
+     * room 채널은 room 인가 함수가 `publisher: true` 를 돌려준 로그인 멤버도 그 room 의 방송인이다 (6.7.0+).
      * 구독할 때 정해지므로 역할이나 카테고리 설정이 바뀌면 다시 구독해야 반영된다.
      */
     isPublisher: boolean;
@@ -7978,13 +8012,27 @@ interface CategoryInfo {
 /** 메시지 데이터 */
 interface RealtimeMessage<T = unknown> {
     id?: string;
+    /** 메시지가 온 채널 이름. room 채널이면 `category:room` 이다. */
     category: string;
+    /**
+     * 보낸 연결의 클라이언트 ID(접속할 때 `client_id` 로 보내는 값). **클라이언트가 정해서 보내는 값이라
+     * 누구나 다른 값을 흉내 낼 수 있다** — 화면 표시나 내 메시지 구분 정도에만 쓰고, 누가 보냈는지
+     * 믿어야 하는 판단(권한, 점수, 신고)에는 {@link RealtimeMessage.fromMember} 를 쓴다.
+     */
     from?: string;
+    /**
+     * 보낸 사람의 앱 멤버 ID — 서버가 검증한 값이다 (6.7.0+, platform-issue 01a15e86). 보낸 연결이
+     * 앱 멤버 `accessToken` 으로 접속했을 때만 있고, 공개 키(익명) 연결이 보낸 메시지에는 없다.
+     * `from` 이나 `data` 안의 값과 달리 클라이언트가 위조할 수 없다. 실시간 메시지와 히스토리 모두에
+     * 실린다(구버전 서버는 보내지 않는다).
+     */
+    fromMember?: string;
     data: T;
     sentAt: number;
     /**
-     * 보낸 연결이 이 카테고리의 방송인이라는 **서버 보증** (6.6.0+). `data` 안의 값과 달리 클라이언트가
-     * 위조할 수 없다 — 방송인 메시지만 골라 처리할 때 이 값으로 가린다. 히스토리 메시지에는 없다.
+     * 보낸 연결이 이 카테고리(room 채널이면 그 room)의 방송인이라는 **서버 보증** (6.6.0+). `data` 안의
+     * 값과 달리 클라이언트가 위조할 수 없다 — 방송인 메시지만 골라 처리할 때 이 값으로 가린다.
+     * 히스토리 메시지에는 없다.
      */
     fromPublisher?: boolean;
 }
@@ -8045,6 +8093,17 @@ interface SendOptions {
 interface Subscription {
     /** 카테고리 정보 */
     info: CategoryInfo;
+    /**
+     * 서버에 구독한 채널 이름 (6.7.0+). room 을 구독했으면 `category:room`, 아니면 카테고리 이름이다.
+     * `realtime.unsubscribe()`, `realtime.markRead()`, `realtime.onReadReceipt()` 처럼 이름을 받는
+     * 메서드에는 이 값을 넘긴다.
+     */
+    readonly channel: string;
+    /**
+     * 구독한 room (6.7.0+). `subscribe(category, { room })` 이나 `subscribe('category:room')` 으로
+     * 구독했을 때만 있다.
+     */
+    readonly room?: string;
     /** 메시지 전송 */
     send<T = unknown>(data: T, options?: SendOptions): Promise<void>;
     /** 히스토리 조회 (persist=true인 경우만) */
@@ -8299,21 +8358,35 @@ declare class RealtimeAPI {
     disconnect(): void;
     /**
      * 카테고리 구독
+     *
+     * `options.room` 을 주면 그 카테고리의 room 하나를 구독한다 (6.7.0+). 서버 채널 이름은
+     * `${category}:${room}` 이고, 구독 객체의 `send` / `getHistory` / `unsubscribe` / `onMessage`, 재연결 뒤
+     * 다시 구독하기는 모두 이 채널 이름으로 동작한다(`subscription.channel`).
+     *
+     * @example
+     * ```typescript
+     * const stage = await client.realtime.subscribe('concert', { room: 'show-1025' })
+     * stage.channel          // 'concert:show-1025'
+     * stage.room             // 'show-1025'
+     * stage.info.isPublisher // room 인가 함수가 publisher: true 를 돌려준 로그인 멤버면 true
+     * ```
      */
     subscribe(category: string, options?: SubscribeOptions): Promise<Subscription>;
     /**
      * 구독 해제
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      */
     unsubscribe(category: string): Promise<void>;
     /**
      * 메시지 전송
-     * @param category 카테고리 이름
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      * @param data 전송할 데이터
      * @param options 전송 옵션 (includeSelf: 발신자도 메시지 수신 여부, 기본값 true)
      */
     sendMessage<T = unknown>(category: string, data: T, options?: SendOptions): Promise<void>;
     /**
      * 히스토리 조회
+     * @param category 카테고리 이름. room 을 구독했으면 채널 이름(`category:room`, `subscription.channel`)
      */
     getHistory<T = unknown>(category: string, limit?: number): Promise<HistoryResponse<T>>;
     /**
@@ -8562,18 +8635,25 @@ declare class RealtimeAPI {
      * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
      * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
      * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
-     * 세션당 한 번만 묻는다.
+     * 인스턴스당 한 번만 묻고, 같은 baseUrl 의 인스턴스끼리는 진행 중인 조회와 배운 결과를 함께 쓴다
+     * (6.7.0+, HttpClient.primeEdgeHints 참고 — 한 페이지의 인스턴스 10개가 동시에 물어 대부분 1.5초를 넘기던
+     * platform-issue 01a15e81).
      */
     private primeDirectRealtime;
     /**
      * 첫 연결을 연결 제한 시간(`timeout`) 안에서 다시 시도한다 (6.6.0+, platform-issue 01a15e24).
      *
-     * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`):
-     *   그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때 앱이 재시도를 짜지 않아도 된다.
+     * - 서버가 재시도 시각을 알려 준 거부(`retryAfterMs`, 예: 한 IP 에서 연결이 몰린 `rate_limited`, 인증 서버가
+     *   잠깐 닿지 않는 `auth_unavailable`): 그 시각에 지터를 더해 다시 붙는다. 공연 시작처럼 한꺼번에 들어올 때
+     *   앱이 재시도를 짜지 않아도 된다.
+     * - `rate_limited` / `auth_unavailable` 인데 재시도 시각이 없으면(사유 프레임 없이 close 코드만 왔거나 구버전
+     *   서버) 지수 백오프로 다시 한다. `auth_unavailable` 은 6.6.0 까지 바로 던져, 인증 서버가 몇 초 흔들리는
+     *   동안 들어온 관객이 전부 연결에 실패했다(6.7.0, platform-issue 01a15e81).
      * - 이유 없는 핸드셰이크 실패: 두 번까지 백오프 후 다시 한다. 네트워크가 WebSocket 을 실제로 막으면
      *   매번 실패하고, 앞단의 일시 거부는 다시 하면 붙는다 — 한 번 실패로 SSE 폴백하던 것이 연결 속도
      *   제한을 "네트워크 차단" 으로 오진한 원인이었다.
-     * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다.
+     * - 그 밖의 거부(자격증명, 동시접속 한도 등)와 시간 초과는 바로 던진다. 다시 시도할 시간이 남지 않아도
+     *   마지막 거부를 그대로 던진다(`retryAfterMs` 가 있으면 앱이 그 시각에 다시 부를 수 있다).
      */
     private connectWithRetry;
     private doConnect;