connectbase-client 6.12.0 → 6.14.0

package/dist/index.mjs

@@ -118,9 +118,9 @@ var AdsAPI = class {
 
 // src/types/error.ts
 var ApiError = class extends Error {
-  constructor(statusCode, message, code, details) {
+  constructor(statusCode2, message, code, details) {
     super(message);
-    this.statusCode = statusCode;
+    this.statusCode = statusCode2;
     this.name = "ApiError";
     this.code = code;
     this.details = details;
@@ -256,7 +256,7 @@ var RealtimeConnectionError = class extends Error {
   }
 };
 function isRetryableRealtimeRejection(code) {
-  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "rate_limited" || code === "auth_unavailable" || code === "internal_error";
+  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "rate_limited" || code === "auth_unavailable" || code === "internal_error" || code === "invalid_ws_ticket" || code === "ws_ticket_unavailable";
 }
 var RealtimeRequestError = class extends Error {
   constructor(init) {
@@ -3646,9 +3646,107 @@ var HttpClient = class {
   }
 };
 
+// src/core/ws-ticket.ts
+var WsTicketError = class extends Error {
+  constructor(init) {
+    super(
+      init.message || init.code || `WebSocket ticket request failed (${init.status})`
+    );
+    this.name = "WsTicketError";
+    this.status = init.status;
+    this.code = init.code || "ws_ticket_rejected";
+    this.retryAfterMs = init.retryAfterMs;
+  }
+};
+var DEFAULT_TICKET_TIMEOUT_MS = 5e3;
+var unsupported = /* @__PURE__ */ new Set();
+function supportKey(url, kind) {
+  try {
+    const u = new URL(url);
+    return `${u.origin}|${kind}`;
+  } catch {
+    return `${url}|${kind}`;
+  }
+}
+async function fetchWsTicket(url, kind, credential, options = {}) {
+  const key = supportKey(url, kind);
+  if (unsupported.has(key)) return null;
+  const headers = {};
+  if (credential.kind === "access_token") {
+    headers.Authorization = `Bearer ${credential.value}`;
+  } else {
+    headers["X-Public-Key"] = credential.value;
+  }
+  const { signal, cleanup } = createTimeoutController({
+    timeout: Math.max(
+      1,
+      Math.min(
+        options.timeoutMs ?? DEFAULT_TICKET_TIMEOUT_MS,
+        DEFAULT_TICKET_TIMEOUT_MS
+      )
+    ),
+    signal: options.signal
+  });
+  let response;
+  try {
+    response = await withAbort(
+      fetch(url, { method: "POST", headers, credentials: "omit", signal }),
+      signal
+    );
+  } catch (err) {
+    cleanup();
+    if (options.signal?.aborted) throw err;
+    return null;
+  }
+  try {
+    if (response.ok) {
+      const body2 = await response.json().catch(() => null);
+      return typeof body2?.ticket === "string" && body2.ticket !== "" ? body2.ticket : null;
+    }
+    if (response.status === 404 || response.status === 405 || response.status === 501) {
+      unsupported.add(key);
+      return null;
+    }
+    if (response.status >= 500) return null;
+    const body = await response.json().catch(() => null);
+    const raw = typeof body?.error === "string" ? body.error : void 0;
+    const isCode = raw !== void 0 && /^[a-z0-9_]+$/.test(raw);
+    const code = isCode ? raw : statusCode(response.status);
+    const message = typeof body?.message === "string" ? body.message : raw;
+    const retryAfterMs = typeof body?.retry_after_ms === "number" && body.retry_after_ms > 0 ? body.retry_after_ms : void 0;
+    throw new WsTicketError({
+      status: response.status,
+      code,
+      message,
+      retryAfterMs
+    });
+  } finally {
+    cleanup();
+  }
+}
+function statusCode(status) {
+  switch (status) {
+    case 401:
+      return "unauthorized";
+    case 402:
+      return "quota_exceeded";
+    case 403:
+      return "forbidden";
+    case 429:
+      return "rate_limited";
+    default:
+      return "ws_ticket_rejected";
+  }
+}
+function ticketUrl(base, path) {
+  const httpBase = base.replace(/^ws(s?):\/\//, "http$1://").replace(/\/+$/, "");
+  return `${httpBase}${path}`;
+}
+
 // src/api/database.ts
 var REALTIME_TOKEN_MIN_VALIDITY_SEC = 600;
 var REALTIME_CONNECT_TOKEN_MIN_VALIDITY_SEC = 60;
+var REALTIME_CONNECT_TIMEOUT_MS = 15e3;
 var REALTIME_AUTH_REFRESH_RETRY_MS = 3e4;
 var REALTIME_CLOSING_NOTICE_CODES = /* @__PURE__ */ new Set([
   "TOKEN_EXPIRED",
@@ -4593,15 +4691,52 @@ var DatabaseAPI = class {
       );
       if (fresh) opts.accessToken = fresh;
     }
-    return this.doRealtimeConnect();
+    let ticket;
+    try {
+      ticket = await this.realtimeTicket();
+    } catch (e) {
+      if (e instanceof WsTicketError) {
+        if (e.status === 429 && this.realtimeOptions) {
+          this.attemptRealtimeReconnect();
+        } else {
+          this.setRealtimeState("disconnected");
+        }
+        const err = new RealtimeConnectionError({
+          code: e.code,
+          message: e.message,
+          closeCode: 4e3 + e.status,
+          retryAfterMs: e.retryAfterMs
+        });
+        this.realtimeOnError?.(err);
+        throw err;
+      }
+      throw e;
+    }
+    return this.doRealtimeConnect(ticket);
   }
-  doRealtimeConnect() {
+  /**
+   * 연결 시도 한 번에 쓸 1회용 티켓을 받는다(core/ws-ticket.ts). 브라우저 WebSocket 은 헤더를 못 붙여 예전에는 멤버 토큰을
+   * URL(`?access_token=`)에 실었다 — 이제 헤더로 티켓을 받아 `?ticket=` 만 싣는다. 서버가 티켓을 모르거나(구버전) 잠시 못
+   * 주면 null 이고 예전처럼 붙는다. cross-app OAuth 토큰도 같은 경로다(서버가 티켓에서 토큰을 되살려 같은 검증을 한다).
+   */
+  async realtimeTicket() {
+    const opts = this.realtimeOptions;
+    if (!opts?.accessToken) return null;
+    const baseUrl = opts.dataServerUrl || this.http.getBaseUrl();
+    return fetchWsTicket(
+      ticketUrl(baseUrl, "/v1/database/realtime/ws-ticket"),
+      "data.realtime",
+      { kind: "access_token", value: opts.accessToken },
+      { timeoutMs: REALTIME_CONNECT_TIMEOUT_MS }
+    );
+  }
+  doRealtimeConnect(ticket = null) {
     if (!this.realtimeOptions)
       return Promise.reject(new Error("No realtime options"));
     this.setRealtimeState("connecting");
     const baseUrl = this.realtimeOptions.dataServerUrl || this.http.getBaseUrl();
     const wsUrl = baseUrl.replace(/^http/, "ws");
-    let url = `${wsUrl}/v1/database/realtime/ws?access_token=${encodeURIComponent(this.realtimeOptions.accessToken)}`;
+    let url = ticket ? `${wsUrl}/v1/database/realtime/ws?ticket=${encodeURIComponent(ticket)}` : `${wsUrl}/v1/database/realtime/ws?access_token=${encodeURIComponent(this.realtimeOptions.accessToken)}`;
     this.realtimeTokenRefresh = this.http.canRefreshMemberToken(
       this.realtimeOptions.accessToken
     );
@@ -4620,7 +4755,7 @@ var DatabaseAPI = class {
             this.setRealtimeState("disconnected");
             reject(new Error("Connection timeout"));
           }
-        }, 15e3);
+        }, REALTIME_CONNECT_TIMEOUT_MS);
         this.realtimeWs.onopen = () => {
           if (!settled) {
             settled = true;
@@ -5161,7 +5296,7 @@ var EndpointAPI = class {
       );
     }
     const baseUrl = this.http.getBaseUrl().replace(/\/+$/, "");
-    const ticketUrl = `${baseUrl}/v1/proxy/${encodeURIComponent(label)}/ws-ticket`;
+    const ticketUrl2 = `${baseUrl}/v1/proxy/${encodeURIComponent(label)}/ws-ticket`;
     const ticketHeaders = new Headers();
     const pk = this.http.getPublicKey();
     if (!pk) {
@@ -5170,7 +5305,7 @@ var EndpointAPI = class {
       );
     }
     ticketHeaders.set("X-Public-Key", pk);
-    const ticketRes = await fetch(ticketUrl, {
+    const ticketRes = await fetch(ticketUrl2, {
       method: "POST",
       headers: ticketHeaders,
       signal: opts.signal
@@ -5868,20 +6003,54 @@ var GameRoom = class {
    * 게임 서버에 연결
    */
   connect(roomId) {
-    return new Promise((resolve, reject) => {
-      if (this.ws?.readyState === WebSocket.OPEN) {
-        resolve();
-        return;
-      }
-      if (!this.config.appId) {
-        reject(
-          new Error(
-            "cb.game: appId is required to connect. Pass it to `new ConnectBase({ appId })` or per-client via `cb.game.createClient({ appId, clientId })`."
-          )
-        );
-        return;
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      return Promise.resolve();
+    }
+    if (!this.config.appId) {
+      return Promise.reject(
+        new Error(
+          "cb.game: appId is required to connect. Pass it to `new ConnectBase({ appId })` or per-client via `cb.game.createClient({ appId, clientId })`."
+        )
+      );
+    }
+    if (!this.config.clientId) {
+      return Promise.reject(
+        new Error(
+          "cb.game: clientId is required to build a game connection URL. Pass it via `cb.game.createClient({ appId, clientId })`."
+        )
+      );
+    }
+    return this.connectionTicket().then(
+      (ticket) => this.openSocket(roomId, ticket)
+    );
+  }
+  /**
+   * 연결 시도 한 번에 쓸 1회용 티켓을 받는다(core/ws-ticket.ts). 브라우저 WebSocket 은 헤더를 못 붙여 예전에는 멤버
+   * 토큰(`?token=`)과 공개 키(`?public_key=`)를 URL 에 실었다 — 이제 헤더로 티켓을 받아 `?ticket=` 만 싣는다. 서버가
+   * 티켓을 모르거나(구버전) 잠시 못 주면 null 이고 예전처럼 붙는다. 발급이 자격증명을 거부하면 {@link GameError} 로 던진다.
+   */
+  async connectionTicket() {
+    const { accessToken, publicKey, appId, gameServerUrl } = this.config;
+    if (!accessToken && !publicKey || !appId || !gameServerUrl) return null;
+    try {
+      return await fetchWsTicket(
+        ticketUrl(
+          gameServerUrl,
+          `/v1/game/${encodeURIComponent(appId)}/ws-ticket`
+        ),
+        "game.ws",
+        accessToken ? { kind: "access_token", value: accessToken } : { kind: "public_key", value: publicKey }
+      );
+    } catch (e) {
+      if (e instanceof WsTicketError) {
+        throw new GameError({ code: e.code, message: e.message });
       }
-      const url = this.buildConnectionUrl(roomId);
+      throw e;
+    }
+  }
+  openSocket(roomId, ticket) {
+    return new Promise((resolve, reject) => {
+      const url = this.buildConnectionUrl(roomId, ticket);
       this.ws = new WebSocket(url);
       const onOpen = () => {
         this._isConnected = true;
@@ -6137,7 +6306,7 @@ var GameRoom = class {
     });
   }
   // Private methods
-  buildConnectionUrl(roomId) {
+  buildConnectionUrl(roomId, ticket) {
     const baseUrl = this.config.gameServerUrl;
     const wsUrl = baseUrl.replace(/^http/, "ws");
     const params = new URLSearchParams();
@@ -6150,11 +6319,15 @@ var GameRoom = class {
     if (roomId) {
       params.set("room_id", roomId);
     }
-    if (this.config.publicKey) {
-      params.set("public_key", this.config.publicKey);
-    }
-    if (this.config.accessToken) {
-      params.set("token", this.config.accessToken);
+    if (ticket) {
+      params.set("ticket", ticket);
+    } else {
+      if (this.config.publicKey) {
+        params.set("public_key", this.config.publicKey);
+      }
+      if (this.config.accessToken) {
+        params.set("token", this.config.accessToken);
+      }
     }
     if (!this.config.appId) {
       throw new Error(
@@ -10011,7 +10184,14 @@ var ConnectCancelledError = class extends Error {
   }
 };
 var MAX_HANDSHAKE_RETRIES = 2;
-var RETRY_IN_CONNECT_CODES = /* @__PURE__ */ new Set(["rate_limited", "auth_unavailable"]);
+var RETRY_IN_CONNECT_CODES = /* @__PURE__ */ new Set([
+  "rate_limited",
+  "auth_unavailable",
+  // 1회용 티켓이 업그레이드에서 거부됐다(만료, 이미 쓰임, 저장소 일시 장애). 다음 시도는 새 티켓을 받거나, 저장소가
+  // 없으면 예전 방식으로 붙는다(core/ws-ticket.ts).
+  "invalid_ws_ticket",
+  "ws_ticket_unavailable"
+]);
 var CONNECTION_TOKEN_MIN_VALIDITY_SEC = 600;
 var CONNECT_TOKEN_MIN_VALIDITY_SEC = 60;
 var AUTH_REFRESH_RETRY_MS = 3e4;
@@ -11126,7 +11306,10 @@ var RealtimeAPI = class {
       for (let attempt = 1; ; attempt++) {
         try {
           await this.prepareConnectToken();
-          await this.doConnect(Math.max(deadline - Date.now(), 1));
+          const ticket = await this.connectTicket(
+            Math.max(deadline - Date.now(), 1)
+          );
+          await this.doConnect(Math.max(deadline - Date.now(), 1), ticket);
           return;
         } catch (e) {
           let wait = null;
@@ -11169,7 +11352,39 @@ var RealtimeAPI = class {
       this.initialConnecting = false;
     }
   }
-  async doConnect(timeoutMs = this.options.timeout) {
+  /**
+   * 연결 시도 한 번에 쓸 1회용 티켓을 받는다(core/ws-ticket.ts). 브라우저 WebSocket 은 헤더를 못 붙여 예전에는 멤버
+   * 토큰과 공개 키를 URL 에 실었다 — 이제 헤더로 티켓을 받아 `?ticket=` 만 싣는다. 티켓은 한 번만 쓰이므로 시도마다
+   * 새로 받는다.
+   *
+   * 서버가 티켓을 모르거나(구버전) 잠시 못 주면 null 이고, doConnect 가 예전처럼 자격증명을 URL 에 싣는다. 발급이
+   * 자격증명을 거부하면 업그레이드 거부와 같은 {@link RealtimeConnectionError} 로 던진다 — 재시도 규칙이 같다.
+   */
+  async connectTicket(timeoutMs) {
+    const accessToken = this.options.accessToken;
+    const publicKey = accessToken ? void 0 : this.http.getPublicKey();
+    if (!accessToken && !publicKey) return null;
+    try {
+      return await fetchWsTicket(
+        ticketUrl(this.socketUrl, "/v1/realtime/ws-ticket"),
+        "socket.realtime",
+        accessToken ? { kind: "access_token", value: accessToken } : { kind: "public_key", value: publicKey },
+        { timeoutMs }
+      );
+    } catch (e) {
+      if (e instanceof WsTicketError) {
+        this.log(`WebSocket ticket rejected: ${e.code} (${e.status})`);
+        throw new RealtimeConnectionError({
+          code: e.code,
+          message: e.message,
+          closeCode: 4e3 + e.status,
+          retryAfterMs: e.retryAfterMs
+        });
+      }
+      throw e;
+    }
+  }
+  async doConnect(timeoutMs = this.options.timeout, ticket = null) {
     return new Promise((resolve, reject) => {
       this.state = "connecting";
       this.notifyStateChange();
@@ -11178,9 +11393,10 @@ var RealtimeAPI = class {
       const usingDirect = !!directWsBase;
       const wsUrl = (directWsBase ?? this.socketUrl).replace(/^http/, "ws");
       let url;
+      const auth = ticket ? `ticket=${encodeURIComponent(ticket)}` : void 0;
       this.tokenRefreshNegotiated = false;
       if (this.options.accessToken) {
-        url = `${wsUrl}/v1/realtime/auth?access_token=${encodeURIComponent(this.options.accessToken)}&client_id=${this.clientId}`;
+        url = `${wsUrl}/v1/realtime/auth?${auth ?? `access_token=${encodeURIComponent(this.options.accessToken)}`}&client_id=${this.clientId}`;
         if (this.http.canRefreshMemberToken(this.options.accessToken)) {
           this.tokenRefreshNegotiated = true;
           url += "&token_refresh=1";
@@ -11196,7 +11412,7 @@ var RealtimeAPI = class {
           reject(error);
           return;
         }
-        url = `${wsUrl}/v1/realtime/auth?public_key=${encodeURIComponent(publicKey)}&client_id=${this.clientId}`;
+        url = `${wsUrl}/v1/realtime/auth?${auth ?? `public_key=${encodeURIComponent(publicKey)}`}&client_id=${this.clientId}`;
         this.log("Using API Key authentication");
       }
       if (this.userId) {
@@ -11676,7 +11892,9 @@ var RealtimeAPI = class {
         try {
           await this.prepareConnectToken();
           if (this.state !== "reconnecting") return;
-          await this.doConnect();
+          const ticket = await this.connectTicket(this.options.timeout);
+          if (this.state !== "reconnecting") return;
+          await this.doConnect(void 0, ticket);
           this.log("Reconnected successfully, restoring subscriptions...");
           const snapshot = this.pendingRestore;
           this.pendingRestore = null;
@@ -12657,32 +12875,41 @@ var SubscriptionAPI = class {
    * 구독 생성
    * 정기결제 구독을 생성합니다.
    *
-   * @param data - 구독 정보
-   * @returns 생성된 구독 정보
+   * **금액과 요금제는 서버가 정합니다.** 브라우저에서는 콘솔 가격표의 정기 상품 `product_id` 만 보내고, 서버가
+   * 금액, 통화, 주기, 플랜명, 무료 체험, MoR PG 가격 ref 를 상품에서 정합니다. 금액을 직접 보내는 형태(레거시)는
+   * 결제 설정의 금액 출처가 `client` 인 앱이거나 서버(시크릿 키, service_role 함수)에서 부를 때만 받습니다.
+   *
+   * @param data - 가격표 정기 상품(`product_id`) 또는 금액과 요금제, 빌링키, 고객 정보 등
+   * @returns 생성된 구독 정보 (`product_id` 포함)
    *
    * @example
    * ```typescript
+   * // 가격표 구독 (권장) — 금액, 주기, 체험 기간은 콘솔 가격표의 premium_month 가 정한다
    * const subscription = await client.subscription.create({
    *     billing_key_id: 'bk_xxxxx',
-   *     plan_name: '프리미엄 플랜',
-   *     amount: 9900,
-   *     billing_cycle: 'monthly',
-   *     billing_day: 15,  // 매월 15일 결제
-   *     trial_days: 7     // 7일 무료 체험
+   *     product_id: 'premium_month',
    * })
    *
-   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * // MoR(dodo/paddle) 구독 + 할인 코드 — PG 가격 ref 도 상품의 provider_price_refs 에서 서버가 고른다
    * const promo = await client.subscription.create({
+   *     product_id: 'premium_month',
+   *     discount_code: 'LAUNCH50', // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   * })
+   *
+   * // 금액 직접 지정 (레거시 앱, 서버 호출) — 가격표 전용 앱에서 브라우저가 보내면 403 client_amount_not_allowed
+   * const legacy = await client.subscription.create({
+   *     billing_key_id: 'bk_xxxxx',
    *     plan_name: '프리미엄 플랜',
    *     amount: 9900,
    *     billing_cycle: 'monthly',
-   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
-   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
-   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
    * })
    * ```
    *
    * @remarks
+   * 권한은 구독의 `product_id` 로 지급합니다(`metadata` 는 클라이언트 값). 가격표 전용 앱의 브라우저 호출은
+   * `start_now: false` 와 `billing_day` 를 쓸 수 없습니다(403 `client_schedule_not_allowed`) — 둘 다 한 번 낸 돈으로 쓰는
+   * 기간을 늘립니다. 무료 체험은 상품의 `trial_days` 가 정합니다.
+   *
    * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
    * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
    * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
@@ -12754,9 +12981,9 @@ var SubscriptionAPI = class {
    *
    * @example
    * ```typescript
+   * // 서버(시크릿 키, service_role 함수)에서 다른 가격표 상품으로 바꾸기 — 다음 청구부터 새 금액
    * await client.subscription.update(subscriptionId, {
-   *     plan_name: '엔터프라이즈 플랜',
-   *     amount: 29900
+   *     product_id: 'enterprise_month',
    * })
    *
    * // 다음 결제일을 특정 날짜로 옮기기 (기간권·보상)
@@ -12942,11 +13169,10 @@ var SubscriptionAPI = class {
    *
    * @example
    * ```typescript
+   * // 가격표 정기 상품으로 바꾼다 — 새 PG 가격 ref 와 플랜명은 서버가 상품에서 정한다
    * await client.subscription.changePlan(subscriptionId, {
-   *     provider_price_ref: 'pri_family_monthly', // Dodo 는 'pdt_*'
-   *     plan_name: '가족 플랜',
-   *     amount: 24900,
-   *     proration_mode: 'prorated_immediately',
+   *     product_id: 'family_month',
+   *     proration_mode: 'prorated_immediately', // 브라우저는 지금 정산하는 모드만
    * })
    * ```
    */
@@ -12979,7 +13205,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * const preview = await client.subscription.previewChangePlan(subscriptionId, {
-   *     provider_price_ref: 'pri_family_monthly',
+   *     product_id: 'family_month',
    * })
    * // 통화를 함께 포맷한다 — 금액만 쓰면 다통화에서 거짓 금액이 된다
    * format(preview.immediate_charge_amount, preview.currency)
@@ -13033,10 +13259,11 @@ var SubscriptionAPI = class {
    *
    * @example
    * ```typescript
+   * // 가격표 단건 상품으로 청구 — 금액과 상품명은 서버가 정한다
    * const result = await client.subscription.chargeWithBillingKey({
    *     billing_key_id: 'bk_xxxxx',
-   *     amount: 15000,
-   *     order_name: '추가 결제'
+   *     product_id: 'gem_100',
+   *     quantity: 2,
    * })
    *
    * if (result.status === 'done') {
@@ -13270,8 +13497,8 @@ var SupportAPI = class {
   }
 };
 function detectSdkVersion() {
-  if ("6.12.0") {
-    return "6.12.0";
+  if ("6.14.0") {
+    return "6.14.0";
   }
   return "unknown";
 }
@@ -14165,7 +14392,14 @@ var WebRTCAPI = class _WebRTCAPI {
     this.currentRoomId = null;
     this.currentPeerId = null;
     this.currentUserId = null;
-    this.isBroadcaster = false;
+    /** connect 가 요청한 방송자 역할 (switchRoom 이 이어받는다) */
+    this.broadcasterRequested = false;
+    /** 서버가 정한 방송자 역할 (`joined` 의 is_broadcaster) */
+    this.broadcasterGranted = false;
+    /** 비공개 룸 허용 목록 요청 (이 연결에서만 쓴다) */
+    this.allowedMemberIds = null;
+    this.privateRoom = false;
+    this.warningListeners = [];
     this.localStream = null;
     this.channelType = "interactive";
     // 피어 연결 관리
@@ -14219,7 +14453,10 @@ var WebRTCAPI = class _WebRTCAPI {
     this.setState("connecting");
     this.currentRoomId = options.roomId;
     this.currentUserId = options.userId || null;
-    this.isBroadcaster = options.isBroadcaster || false;
+    this.broadcasterRequested = options.isBroadcaster || false;
+    this.broadcasterGranted = false;
+    this.allowedMemberIds = options.allowedMemberIds ? [...options.allowedMemberIds] : null;
+    this.privateRoom = false;
     this.localStream = options.localStream || null;
     if (this.iceServers.length === 0) {
       try {
@@ -14230,9 +14467,35 @@ var WebRTCAPI = class _WebRTCAPI {
     }
     return this.connectWebSocket();
   }
-  connectWebSocket() {
+  async connectWebSocket() {
+    const before = this.wsGeneration;
+    const ticket = await this.signalingTicket();
+    if (this.wsGeneration !== before) {
+      throw new Error("\uC5F0\uACB0\uC774 \uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4");
+    }
+    return this.openSignalingSocket(ticket);
+  }
+  /**
+   * 연결 시도 한 번에 쓸 1회용 티켓을 받는다(core/ws-ticket.ts). 브라우저 WebSocket 은 헤더를 못 붙여 예전에는 멤버 토큰
+   * (`?access_token=`)과 공개 키(`?public_key=`)를 URL 에 실었다 — 이제 헤더로 티켓을 받아 `?ticket=` 만 싣는다. 서버가
+   * 티켓을 모르거나(구버전) 잠시 못 주면 null 이고 예전처럼 붙는다. 발급이 자격증명을 거부하면 그 이유로 던진다.
+   */
+  async signalingTicket() {
+    const accessToken = this.http.getAccessToken();
+    const publicKey = accessToken ? void 0 : this.http.getPublicKey();
+    if (!accessToken && !publicKey || !this.appId) return null;
+    return fetchWsTicket(
+      ticketUrl(
+        this.webrtcUrl,
+        `/v1/apps/${encodeURIComponent(this.appId)}/signaling/ws-ticket`
+      ),
+      "webrtc.signaling",
+      accessToken ? { kind: "access_token", value: accessToken } : { kind: "public_key", value: publicKey }
+    );
+  }
+  openSignalingSocket(ticket) {
     return new Promise((resolve, reject) => {
-      const wsUrl = this.buildWebSocketUrl();
+      const wsUrl = this.buildWebSocketUrl(ticket);
       const generation = ++this.wsGeneration;
       const ws = new WebSocket(wsUrl);
       this.ws = ws;
@@ -14251,13 +14514,16 @@ var WebRTCAPI = class _WebRTCAPI {
           return;
         }
         this.reconnectAttempts = 0;
+        const joinData = {
+          is_broadcaster: this.broadcasterRequested
+        };
+        if (this.allowedMemberIds) {
+          joinData.allowed_member_ids = this.allowedMemberIds;
+        }
         this.sendSignaling({
           type: "join",
           room_id: this.currentRoomId,
-          data: {
-            user_id: this.currentUserId,
-            is_broadcaster: this.isBroadcaster
-          }
+          data: joinData
         });
       };
       ws.onmessage = async (event) => {
@@ -14298,12 +14564,14 @@ var WebRTCAPI = class _WebRTCAPI {
     ws.onerror = null;
     ws.onclose = null;
   }
-  buildWebSocketUrl() {
+  buildWebSocketUrl(ticket = null) {
     const wsBase = this.webrtcUrl.replace("https://", "wss://").replace("http://", "ws://");
     const publicKey = this.http.getPublicKey();
     const accessToken = this.http.getAccessToken();
     let authParam = "";
-    if (accessToken) {
+    if (ticket) {
+      authParam = `ticket=${encodeURIComponent(ticket)}`;
+    } else if (accessToken) {
       authParam = `access_token=${encodeURIComponent(accessToken)}`;
     } else if (publicKey) {
       authParam = `public_key=${encodeURIComponent(publicKey)}`;
@@ -14325,6 +14593,8 @@ var WebRTCAPI = class _WebRTCAPI {
           if (data.channel_type) {
             this.channelType = data.channel_type;
           }
+          this.broadcasterGranted = data.is_broadcaster === true;
+          this.privateRoom = data.private === true;
           const peers = data.peers || [];
           for (const peer of peers) {
             if (peer.peer_id !== this.currentPeerId) {
@@ -14365,9 +14635,16 @@ var WebRTCAPI = class _WebRTCAPI {
           await this.handleICECandidate(msg.peer_id, msg.candidate);
         }
         break;
+      case "warning": {
+        const data = msg.data && typeof msg.data === "object" ? msg.data : {};
+        this.emitWarning({
+          code: typeof data.code === "string" ? data.code : "unknown",
+          message: typeof data.message === "string" ? data.message : ""
+        });
+        break;
+      }
       case "error": {
-        const errorMsg = typeof msg.data === "string" ? msg.data : "Unknown error";
-        const error = new Error(errorMsg);
+        const error = new Error(_WebRTCAPI.signalingErrorMessage(msg.data));
         this.emitError(error);
         reject?.(error);
         break;
@@ -14465,6 +14742,19 @@ var WebRTCAPI = class _WebRTCAPI {
     }
     this.remoteStreams.delete(remotePeerId);
   }
+  /**
+   * 서버 error 메시지의 data 에서 안내 문구를 꺼낸다. 대부분은 문자열이지만 할당량, 동시접속 초과는
+   * `{ error, message, ... }` 객체로 온다.
+   */
+  static signalingErrorMessage(data) {
+    if (typeof data === "string" && data) return data;
+    if (data && typeof data === "object") {
+      const obj = data;
+      if (typeof obj.message === "string" && obj.message) return obj.message;
+      if (typeof obj.error === "string" && obj.error) return obj.error;
+    }
+    return "Unknown error";
+  }
   sendSignaling(msg) {
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
       this.ws.send(JSON.stringify(msg));
@@ -14530,6 +14820,8 @@ var WebRTCAPI = class _WebRTCAPI {
     this.currentRoomId = null;
     this.currentPeerId = null;
     this.localStream = null;
+    this.broadcasterGranted = false;
+    this.privateRoom = false;
     this.setState("disconnected");
   }
   /**
@@ -14547,9 +14839,15 @@ var WebRTCAPI = class _WebRTCAPI {
   async switchRoom(roomId, options = {}) {
     const localStream = options.localStream ?? this.localStream ?? void 0;
     const userId = options.userId ?? this.currentUserId ?? void 0;
-    const isBroadcaster = options.isBroadcaster ?? this.isBroadcaster;
+    const isBroadcaster = options.isBroadcaster ?? this.broadcasterRequested;
     this.disconnect();
-    await this.connect({ roomId, userId, isBroadcaster, localStream });
+    await this.connect({
+      roomId,
+      userId,
+      isBroadcaster,
+      localStream,
+      allowedMemberIds: options.allowedMemberIds
+    });
   }
   /**
    * 소켓, 룸, 이벤트 리스너, 피어 연결을 **독립적으로** 갖는 새 WebRTC 세션을 만든다.
@@ -14602,6 +14900,19 @@ var WebRTCAPI = class _WebRTCAPI {
   getChannelType() {
     return this.channelType;
   }
+  /**
+   * 서버가 정한 방송자 역할인지 조회한다. 요청(`isBroadcaster: true`)과 다를 수 있다 — 익명 연결이나
+   * 채널의 방송자 역할이 없는 회원은 시청자로 참가한다(`onWarning` 으로 이유가 온다).
+   */
+  isBroadcaster() {
+    return this.broadcasterGranted;
+  }
+  /**
+   * 지금 룸이 회원 허용 목록이 있는 비공개 룸인지 조회한다.
+   */
+  isPrivateRoom() {
+    return this.privateRoom;
+  }
   /**
    * 원격 스트림 조회
    */
@@ -14672,6 +14983,24 @@ var WebRTCAPI = class _WebRTCAPI {
       this.errorListeners = this.errorListeners.filter((cb) => cb !== callback);
     };
   }
+  /**
+   * 서버가 join 요청을 바꿨다는 알림 이벤트 (예: 방송자 요청을 시청자로 낮춤)
+   *
+   * @example
+   * ```typescript
+   * cb.webrtc.onWarning(({ code, message }) => {
+   *     if (code === 'broadcaster_role_required') showToast(message)
+   * })
+   * ```
+   */
+  onWarning(callback) {
+    this.warningListeners.push(callback);
+    return () => {
+      this.warningListeners = this.warningListeners.filter(
+        (cb) => cb !== callback
+      );
+    };
+  }
   /**
    * 피어 참가 이벤트
    */
@@ -14717,6 +15046,9 @@ var WebRTCAPI = class _WebRTCAPI {
   emitError(error) {
     this.errorListeners.forEach((cb) => cb(error));
   }
+  emitWarning(warning) {
+    this.warningListeners.forEach((cb) => cb(warning));
+  }
   emitPeerJoined(peerId, info) {
     this.peerJoinedListeners.forEach((cb) => cb(peerId, info));
   }
@@ -14897,11 +15229,35 @@ var WebSocketTransport = class {
     this.onClose = onClose;
     this.onError = onError;
   }
-  connect() {
+  async connect() {
+    const ticket = await this.connectionTicket();
+    return this.openSocket(ticket);
+  }
+  /**
+   * 연결 시도 한 번에 쓸 1회용 티켓(core/ws-ticket.ts). 서버가 티켓을 모르거나(구버전) 잠시 못 주면 null 이고 예전처럼
+   * 자격증명을 URL 에 싣는다. 발급이 자격증명을 거부하면 {@link GameError} 로 던진다.
+   */
+  async connectionTicket() {
+    const { accessToken, publicKey, appId } = this.config;
+    if (!accessToken && !publicKey || !appId) return null;
+    const baseUrl = this.config.gameServerUrl || "wss://game.connectbase.world";
+    try {
+      return await fetchWsTicket(
+        ticketUrl(baseUrl, `/v1/game/${encodeURIComponent(appId)}/ws-ticket`),
+        "game.ws",
+        accessToken ? { kind: "access_token", value: accessToken } : { kind: "public_key", value: publicKey }
+      );
+    } catch (e) {
+      if (e instanceof WsTicketError) {
+        throw new GameError({ code: e.code, message: e.message });
+      }
+      throw e;
+    }
+  }
+  openSocket(ticket) {
     return new Promise((resolve, reject) => {
-      const url = this.buildUrl();
       try {
-        this.ws = new WebSocket(url);
+        this.ws = new WebSocket(this.buildUrl(ticket));
         this.ws.binaryType = "arraybuffer";
       } catch (error) {
         reject(error);
@@ -14931,16 +15287,20 @@ var WebSocketTransport = class {
       this.ws.addEventListener("message", onMessage);
     });
   }
-  buildUrl() {
+  buildUrl(ticket = null) {
     const baseUrl = this.config.gameServerUrl || "wss://game.connectbase.world";
     const wsUrl = baseUrl.replace(/^http/, "ws");
     const params = new URLSearchParams();
     params.set("client_id", requireClientId(this.config.clientId));
-    if (this.config.publicKey) {
-      params.set("public_key", this.config.publicKey);
-    }
-    if (this.config.accessToken) {
-      params.set("token", this.config.accessToken);
+    if (ticket) {
+      params.set("ticket", ticket);
+    } else {
+      if (this.config.publicKey) {
+        params.set("public_key", this.config.publicKey);
+      }
+      if (this.config.accessToken) {
+        params.set("token", this.config.accessToken);
+      }
     }
     if (!this.config.appId) {
       throw new Error(
@@ -15619,6 +15979,7 @@ export {
   RolesAPI,
   SessionManager,
   VideoProcessingError,
+  WsTicketError,
   index_default as default,
   detectInAppBrowser,
   escapeToExternalBrowser,