connectbase-client 0.16.1 → 1.3.0

package/dist/index.js

@@ -61,8 +61,21 @@ var HttpClient = class {
     this.refreshPromise = null;
     this.config = { ...config };
     this.storageKey = this.buildStorageKey();
+    this.warnIfUnsafePersistence();
     this.restoreTokens();
   }
+  warnIfUnsafePersistence() {
+    if (typeof window === "undefined") return;
+    if (this.config.persistence === "localStorage") {
+      console.warn(
+        `[connect-base-client] persistence="localStorage" \uB294 XSS \uC2DC \uD1A0\uD070 \uC601\uAD6C \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4. refresh token \uC740 \uC11C\uBC84 HttpOnly \uCFE0\uD0A4\uB85C \uBC1C\uAE09\uBC1B\uACE0 \uAE30\uBCF8\uAC12('none')\uC744 \uC0AC\uC6A9\uD558\uC138\uC694.`
+      );
+    } else if (this.config.persistence === "sessionStorage") {
+      console.warn(
+        '[connect-base-client] persistence="sessionStorage" \uB294 XSS \uC2DC \uD604\uC7AC \uD0ED \uC138\uC158 \uD0C8\uCDE8 \uC704\uD5D8\uC774 \uC788\uC2B5\uB2C8\uB2E4.'
+      );
+    }
+  }
   updateConfig(config) {
     this.config = { ...this.config, ...config };
   }
@@ -78,7 +91,7 @@ var HttpClient = class {
   }
   // ===== Token Persistence =====
   get persistence() {
-    return this.config.persistence ?? "localStorage";
+    return this.config.persistence ?? "none";
   }
   getStorage() {
     if (typeof window === "undefined") return null;
@@ -86,6 +99,13 @@ var HttpClient = class {
     if (this.persistence === "sessionStorage" && typeof sessionStorage !== "undefined") return sessionStorage;
     return null;
   }
+  /**
+   * AuthAPI 등 내부 사용자가 "현재 persistence 설정된 스토리지"를 확인할 수 있도록 노출.
+   * persistence='none' 이면 null. XSS 완화 기본값을 공유하기 위함.
+   */
+  getPersistenceStorage() {
+    return this.getStorage();
+  }
   buildStorageKey() {
     const credential = this.config.publicKey ?? this.config.secretKey;
     if (!credential) return TOKEN_STORAGE_KEY;
@@ -164,6 +184,12 @@ var HttpClient = class {
   getAccessToken() {
     return this.config.accessToken;
   }
+  /**
+   * JWT(Access Token) 가 설정되어 있는지 확인
+   */
+  hasJWT() {
+    return !!this.config.accessToken;
+  }
   /**
    * Base URL 반환
    */
@@ -347,10 +373,10 @@ function notifyVisitorTracker(memberId) {
     }
   }
 }
-function simpleHash(str) {
+function credentialToStorageKeyHash(credential) {
   let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
+  for (let i = 0; i < credential.length; i++) {
+    const char = credential.charCodeAt(i);
     hash = (hash << 5) - hash + char;
     hash = hash & hash;
   }
@@ -506,8 +532,9 @@ var AuthAPI = class {
    * 저장된 게스트 멤버 토큰 삭제
    */
   clearGuestMemberTokens() {
-    if (typeof sessionStorage === "undefined") return;
-    sessionStorage.removeItem(this.getGuestMemberTokenKey());
+    const storage = this.http.getPersistenceStorage();
+    if (!storage) return;
+    storage.removeItem(this.getGuestMemberTokenKey());
   }
   // ===== Private Methods =====
   async executeGuestMemberLogin() {
@@ -581,14 +608,15 @@ var AuthAPI = class {
     if (!credential) {
       this.cachedGuestMemberTokenKey = `${GUEST_MEMBER_TOKEN_KEY_PREFIX}default`;
     } else {
-      const keyHash = simpleHash(credential);
+      const keyHash = credentialToStorageKeyHash(credential);
       this.cachedGuestMemberTokenKey = `${GUEST_MEMBER_TOKEN_KEY_PREFIX}${keyHash}`;
     }
     return this.cachedGuestMemberTokenKey;
   }
   getStoredGuestMemberTokens() {
-    if (typeof sessionStorage === "undefined") return null;
-    const stored = sessionStorage.getItem(this.getGuestMemberTokenKey());
+    const storage = this.http.getPersistenceStorage();
+    if (!storage) return null;
+    const stored = storage.getItem(this.getGuestMemberTokenKey());
     if (!stored) return null;
     try {
       return JSON.parse(stored);
@@ -597,8 +625,9 @@ var AuthAPI = class {
     }
   }
   storeGuestMemberTokens(accessToken, refreshToken, memberId) {
-    if (typeof sessionStorage === "undefined") return;
-    sessionStorage.setItem(this.getGuestMemberTokenKey(), JSON.stringify({ accessToken, refreshToken, memberId }));
+    const storage = this.http.getPersistenceStorage();
+    if (!storage) return;
+    storage.setItem(this.getGuestMemberTokenKey(), JSON.stringify({ accessToken, refreshToken, memberId }));
   }
 };
 
@@ -1856,21 +1885,33 @@ var StorageAPI = class {
   }
   /**
    * 파일/폴더 이동
+   *
+   * Public Key 인증만으로는 이 엔드포인트가 노출되지 않습니다. JWT(콘솔 토큰)가 필요합니다.
    */
   async moveFile(storageId, fileId, data) {
-    const prefix = this.getPublicPrefix();
+    if (this.http.hasPublicKey() && !this.http.hasJWT()) {
+      throw new Error(
+        "storage.moveFile requires JWT (console token) auth; not available with Public Key alone."
+      );
+    }
     await this.http.post(
-      `${prefix}/storages/files/${storageId}/items/${fileId}/move`,
+      `/v1/storages/files/${storageId}/items/${fileId}/move`,
       data
     );
   }
   /**
    * 파일/폴더 이름 변경
+   *
+   * Public Key 인증만으로는 이 엔드포인트가 노출되지 않습니다. JWT(콘솔 토큰)가 필요합니다.
    */
   async renameFile(storageId, fileId, data) {
-    const prefix = this.getPublicPrefix();
+    if (this.http.hasPublicKey() && !this.http.hasJWT()) {
+      throw new Error(
+        "storage.renameFile requires JWT (console token) auth; not available with Public Key alone."
+      );
+    }
     return this.http.patch(
-      `${prefix}/storages/files/${storageId}/items/${fileId}/rename`,
+      `/v1/storages/files/${storageId}/items/${fileId}/rename`,
       data
     );
   }
@@ -3303,7 +3344,10 @@ var WebRTCAPI = class {
    * ICE 서버 목록 조회
    */
   async getICEServers() {
-    const response = await this.http.get("/v1/ice-servers");
+    if (!this.appId) {
+      throw new Error("WebRTC getICEServers \uC5D0\uB294 appId \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. ConnectBase \uCD08\uAE30\uD654 \uC2DC appId \uB97C \uC124\uC815\uD558\uC138\uC694.");
+    }
+    const response = await this.http.get(`/v1/apps/${this.appId}/ice-servers`);
     this.iceServers = response.ice_servers;
     return response.ice_servers;
   }
@@ -3774,13 +3818,13 @@ var WebRTCAPI = class {
    * 앱의 WebRTC 통계 조회
    */
   async getStats(appID) {
-    return this.http.get(`/v1/apps/${appID}/webrtc/stats`);
+    return this.http.get(`/v1/apps/${appID}/stats`);
   }
   /**
    * 앱의 활성 룸 목록 조회
    */
   async getRooms(appID) {
-    return this.http.get(`/v1/apps/${appID}/webrtc/rooms`);
+    return this.http.get(`/v1/apps/${appID}/rooms`);
   }
 };
 
@@ -4219,6 +4263,43 @@ var OAuthAPI = class {
     this.http.setTokens(accessToken, refreshToken);
     return result;
   }
+  /**
+   * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
+   *
+   * 서버가 `OAUTH_CODE_ONLY=true` 모드면 리다이렉트 URL 에 토큰 대신 `code` 만 포함됩니다.
+   * 이 메서드는 code 를 `POST /v1/auth/oauth/exchange` 로 교환하고 토큰을 자동 저장합니다.
+   *
+   * 권장 호출 순서:
+   *   1) `cb.oauth.exchangeCodeFromCallback()` 먼저 — code-only 모드면 성공
+   *   2) null 반환 시 `cb.oauth.getCallbackResult()` 폴백 (legacy 토큰-in-URL 모드)
+   *
+   * @example
+   * ```typescript
+   * const result = await cb.oauth.exchangeCodeFromCallback()
+   *   ?? cb.oauth.getCallbackResult()
+   * ```
+   */
+  async exchangeCodeFromCallback() {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    if (!code) return null;
+    if (params.get("error")) return null;
+    const resp = await this.http.post("/v1/auth/oauth/exchange", { code });
+    const result = {
+      access_token: resp.access_token,
+      refresh_token: resp.refresh_token,
+      member_id: resp.member_id,
+      is_new_member: resp.is_new_member,
+      state: params.get("state") || void 0
+    };
+    if (window.opener) {
+      window.opener.postMessage({ type: "oauth-callback", ...result }, "*");
+      window.close();
+      return result;
+    }
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
 };
 
 // src/api/payment.ts
@@ -4241,38 +4322,67 @@ var PaymentAPI = class {
    *
    * @example
    * ```typescript
-   * const prepareResult = await client.payment.prepare({
+   * const result = await cb.payment.prepare({
    *     amount: 10000,
-   *     order_name: '테스트 상품',
+   *     order_name: '프리미엄 1개월',
    *     customer_email: 'test@example.com',
    *     customer_name: '홍길동'
    * })
    *
-   * // 토스 결제 위젯 초기화
-   * const tossPayments = TossPayments(prepareResult.toss_client_key)
-   * await tossPayments.requestPayment('카드', {
-   *     amount: prepareResult.amount,
-   *     orderId: prepareResult.order_id,
-   *     orderName: prepareResult.order_name,
-   *     customerKey: prepareResult.customer_key,
-   *     successUrl: prepareResult.success_url,
-   *     failUrl: prepareResult.fail_url
-   * })
+   * // Toss V2 결제 플로우
+   * if (result.payment_provider === 'toss') {
+   *   const tossPayments = TossPayments(result.toss_client_key)
+   *   const payment = tossPayments.payment({ customerKey: result.customer_key })
+   *   await payment.requestPayment({
+   *     method: 'CARD',
+   *     amount: { currency: 'KRW', value: result.amount },
+   *     orderId: result.order_id,
+   *     orderName: result.order_name,
+   *     successUrl: result.success_url,
+   *     failUrl: result.fail_url,
+   *   })
+   * }
    *
-   * // Stripe 결제 플로우:
-   * // const result = await client.payment.prepare({ amount: 1000, order_name: 'Product' })
-   * // if (result.payment_provider === 'stripe') {
-   * //   const stripe = await loadStripe(result.stripe_publishable_key)
-   * //   const elements = stripe.elements({ clientSecret: result.stripe_client_secret })
-   * //   // Mount PaymentElement, then:
-   * //   // stripe.confirmPayment({ elements, redirect: 'if_required' })
-   * // }
+   * // Stripe 결제 플로우
+   * if (result.payment_provider === 'stripe') {
+   *   const stripe = await loadStripe(result.stripe_publishable_key)
+   *   const elements = stripe.elements({ clientSecret: result.stripe_client_secret })
+   *   // Mount PaymentElement, then:
+   *   // stripe.confirmPayment({ elements, redirect: 'if_required' })
+   * }
    * ```
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
     return this.http.post(`${prefix}/payments/prepare`, data);
   }
+  /**
+   * Stripe-hosted 결제 페이지 세션 생성 (client_secret 미노출 플로우).
+   *
+   * Elements 플로우(`prepare`) 대신 Stripe-hosted Checkout 페이지로 리다이렉트하고 싶을 때 사용.
+   * 응답에 `session_url` 이 포함되며, 브라우저를 해당 URL 로 이동시키면 Stripe 가 카드 입력·결제를 처리한 뒤
+   * `success_url` / `cancel_url` 로 복귀한다. `client_secret` 은 서버·클라이언트 어디에도 노출되지 않는다.
+   *
+   * @param data - 결제 세션 정보 (금액, 통화, 상품명, success/cancel URL 등)
+   * @returns session_id, session_url (redirect 대상)
+   *
+   * @example
+   * ```typescript
+   * const sess = await client.payment.createCheckoutSession({
+   *   amount: 1000,
+   *   currency: 'USD',
+   *   product_name: 'Premium Subscription',
+   *   success_url: 'https://app.example.com/success?session_id={CHECKOUT_SESSION_ID}',
+   *   cancel_url: 'https://app.example.com/cancel',
+   *   customer_email: 'user@example.com',
+   * })
+   * window.location.href = sess.session_url
+   * ```
+   */
+  async createCheckoutSession(data) {
+    const prefix = this.getPublicPrefix();
+    return this.http.post(`${prefix}/payments/checkout-session`, data);
+  }
   /**
    * 결제 승인
    * 토스에서 결제 완료 후 콜백으로 받은 정보로 결제를 최종 승인합니다.
@@ -6077,41 +6187,19 @@ var GameAPI = class {
   }
   /**
    * 룸 생성 (HTTP, gRPC 대안)
+   *
+   * @deprecated 현재 SDK public 경로로 노출되지 않습니다. 콘솔(admin) 에서 진행하거나 백엔드 public 경로 오픈을 요청하세요.
    */
-  async createRoom(appId, config = {}) {
-    const id = appId || this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms`, {
-      method: "POST",
-      headers: {
-        ...this.getHeaders(),
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        app_id: appId,
-        category_id: config.categoryId,
-        room_id: config.roomId,
-        tick_rate: config.tickRate,
-        max_players: config.maxPlayers,
-        metadata: config.metadata
-      })
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to create room: ${response.statusText}`);
-    }
-    return response.json();
+  async createRoom(_appId, _config = {}) {
+    throw new Error("cb.game.createRoom is not yet publicly available \u2014 use the admin console or request a backend public route.");
   }
   /**
    * 룸 삭제 (HTTP)
+   *
+   * @deprecated 현재 SDK public 경로로 노출되지 않습니다. 콘솔(admin) 에서 진행하거나 백엔드 public 경로 오픈을 요청하세요.
    */
-  async deleteRoom(roomId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms/${roomId}`, {
-      method: "DELETE",
-      headers: this.getHeaders()
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to delete room: ${response.statusText}`);
-    }
+  async deleteRoom(_roomId) {
+    throw new Error("cb.game.deleteRoom is not yet publicly available \u2014 use the admin console or request a backend public route.");
   }
   // ==================== Matchmaking ====================
   /**
@@ -6511,6 +6599,8 @@ var GameAPI = class {
     }));
   }
   // --- Party API ---
+  // 1.1.0 부터 `createParty/leaveParty/kickFromParty/inviteToParty/sendPartyChat` 활성화.
+  // 1.3.0 부터 `acceptPartyInvite/declinePartyInvite` 추가. 직접 join 엔드포인트는 없음 — `joinParty` 는 throw.
   async createParty(playerId, maxSize) {
     const id = this.appId || "";
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties`, {
@@ -6521,16 +6611,49 @@ var GameAPI = class {
     if (!response.ok) throw new Error(`Failed to create party: ${response.statusText}`);
     return response.json();
   }
-  async joinParty(partyId, playerId) {
+  /**
+   * @deprecated 백엔드에서 직접 join 엔드포인트 미제공 — `inviteToParty` → `acceptPartyInvite` 플로우 사용
+   */
+  async joinParty(_partyId, _playerId) {
+    throw new Error("cb.game.joinParty is not supported \u2014 use inviteToParty + acceptPartyInvite flow.");
+  }
+  /**
+   * 파티 초대 수락
+   *
+   * `inviteToParty` 로 생성된 초대 ID 를 수락하여 파티에 합류한다.
+   * 로비 초대(`acceptInvite`) 와 다른 엔드포인트 (`/v1/game/:appID/invites/:inviteID/accept`).
+   */
+  async acceptPartyInvite(inviteId, playerId, displayName) {
     const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/join`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId })
-    });
-    if (!response.ok) throw new Error(`Failed to join party: ${response.statusText}`);
+    const qs = new URLSearchParams({ player_id: playerId });
+    if (displayName) qs.set("display_name", displayName);
+    const response = await fetch(
+      `${this.gameServerUrl}/v1/game/${id}/invites/${inviteId}/accept?${qs.toString()}`,
+      { method: "POST", headers: this.getHeaders() }
+    );
+    if (!response.ok) {
+      const err = await response.json().catch(() => ({}));
+      throw new Error(err.error || `Failed to accept party invite: ${response.statusText}`);
+    }
     return response.json();
   }
+  /**
+   * 파티 초대 거절
+   *
+   * `inviteToParty` 로 생성된 초대 ID 를 거절한다.
+   */
+  async declinePartyInvite(inviteId, playerId) {
+    const id = this.appId || "";
+    const qs = new URLSearchParams({ player_id: playerId });
+    const response = await fetch(
+      `${this.gameServerUrl}/v1/game/${id}/invites/${inviteId}/decline?${qs.toString()}`,
+      { method: "POST", headers: this.getHeaders() }
+    );
+    if (!response.ok) {
+      const err = await response.json().catch(() => ({}));
+      throw new Error(err.error || `Failed to decline party invite: ${response.statusText}`);
+    }
+  }
   async leaveParty(partyId, playerId) {
     const id = this.appId || "";
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/leave`, {
@@ -6563,14 +6686,15 @@ var GameAPI = class {
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/chat`, {
       method: "POST",
       headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, message })
+      body: JSON.stringify({ sender_id: playerId, content: message })
     });
     if (!response.ok) throw new Error(`Failed to send party chat: ${response.statusText}`);
   }
   // --- Spectator API ---
+  // 1.1.0 부터 활성화. 백엔드 엔드포인트는 `/rooms/:roomID/spectators` 를 사용 (기존 `/spectate` 아님).
   async joinSpectator(roomId, playerId) {
     const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms/${roomId}/spectate`, {
+    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms/${roomId}/spectators`, {
       method: "POST",
       headers: { ...this.getHeaders(), "Content-Type": "application/json" },
       body: JSON.stringify({ player_id: playerId })
@@ -6580,10 +6704,9 @@ var GameAPI = class {
   }
   async leaveSpectator(roomId, spectatorId) {
     const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms/${roomId}/spectate/stop`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ spectator_id: spectatorId })
+    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/rooms/${roomId}/spectators/${spectatorId}`, {
+      method: "DELETE",
+      headers: this.getHeaders()
     });
     if (!response.ok) throw new Error(`Failed to leave spectator: ${response.statusText}`);
   }
@@ -6597,27 +6720,30 @@ var GameAPI = class {
     return data.spectators || [];
   }
   // --- Ranking/Leaderboard API ---
-  async getLeaderboard(top) {
+  // 1.1.0 부터 활성화. 백엔드가 `app_id` + `game_type` 쿼리를 요구하므로 SDK 시그니처에 `gameType` 추가.
+  async getLeaderboard(gameType, top = 100, season = "default") {
     const id = this.appId || "";
-    const limit = top || 100;
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/leaderboard/top?limit=${limit}`, {
+    const params = new URLSearchParams({ app_id: id, game_type: gameType, season, limit: String(top) });
+    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/leaderboard/top?${params}`, {
       headers: this.getHeaders()
     });
     if (!response.ok) throw new Error(`Failed to get leaderboard: ${response.statusText}`);
     const data = await response.json();
     return data.entries || [];
   }
-  async getPlayerStats(playerId) {
+  async getPlayerStats(playerId, gameType, season = "default") {
     const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/players/${playerId}/stats`, {
+    const params = new URLSearchParams({ app_id: id, game_type: gameType, season });
+    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/players/${playerId}/stats?${params}`, {
       headers: this.getHeaders()
     });
     if (!response.ok) throw new Error(`Failed to get player stats: ${response.statusText}`);
     return response.json();
   }
-  async getPlayerRank(playerId) {
+  async getPlayerRank(playerId, gameType, season = "default") {
     const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/players/${playerId}/rank`, {
+    const params = new URLSearchParams({ app_id: id, game_type: gameType, season });
+    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/ranking/players/${playerId}/rank?${params}`, {
       headers: this.getHeaders()
     });
     if (!response.ok) throw new Error(`Failed to get player rank: ${response.statusText}`);
@@ -6653,11 +6779,16 @@ var GameAPI = class {
     if (!response.ok) throw new Error(`Failed to set mute: ${response.statusText}`);
   }
   // --- Replay API ---
+  // 1.1.0 부터 활성화. 백엔드에서 `REPLAY_STORAGE_PATH` 환경변수가 설정된 경우에만 동작.
+  // 미설정 시 404 응답 → SDK 가 명시적 에러를 throw.
   async listReplays(roomId) {
     const id = this.appId || "";
     let url = `${this.gameServerUrl}/v1/game/${id}/replays`;
     if (roomId) url += `?room_id=${roomId}`;
     const response = await fetch(url, { headers: this.getHeaders() });
+    if (response.status === 404) {
+      throw new Error("cb.game.listReplays: replay storage is not configured on this server (REPLAY_STORAGE_PATH unset).");
+    }
     if (!response.ok) throw new Error(`Failed to list replays: ${response.statusText}`);
     const data = await response.json();
     return data.replays || [];
@@ -6667,6 +6798,9 @@ var GameAPI = class {
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/replays/${replayId}`, {
       headers: this.getHeaders()
     });
+    if (response.status === 404) {
+      throw new Error("cb.game.getReplay: replay not found or replay storage unconfigured.");
+    }
     if (!response.ok) throw new Error(`Failed to get replay: ${response.statusText}`);
     return response.json();
   }
@@ -6675,6 +6809,9 @@ var GameAPI = class {
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/replays/${replayId}/download`, {
       headers: this.getHeaders()
     });
+    if (response.status === 404) {
+      throw new Error("cb.game.downloadReplay: replay not found or replay storage unconfigured.");
+    }
     if (!response.ok) throw new Error(`Failed to download replay: ${response.statusText}`);
     return response.arrayBuffer();
   }
@@ -6683,6 +6820,9 @@ var GameAPI = class {
     const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/replays/${replayId}/highlights`, {
       headers: this.getHeaders()
     });
+    if (response.status === 404) {
+      throw new Error("cb.game.getReplayHighlights: replay not found or replay storage unconfigured.");
+    }
     if (!response.ok) throw new Error(`Failed to get highlights: ${response.statusText}`);
     const data = await response.json();
     return data.highlights || [];
@@ -6713,15 +6853,18 @@ var AdsAPI = class {
     return this.http.hasPublicKey() ? "/v1/public" : "/v1";
   }
   /**
-   * AdSense 연결 상태 확인
+   * AdSense / AdMob 연결 상태 확인 (중첩 구조)
    *
-   * @returns 연결 상태, 이메일, AdSense 계정 ID
+   * @returns `{ adsense, admob }` 각각 연결 상태·이메일·계정 ID
    *
    * @example
    * ```typescript
    * const status = await cb.ads.getConnectionStatus()
-   * if (status.is_connected) {
-   *     console.log('연결됨:', status.email)
+   * if (status.adsense.is_connected) {
+   *     console.log('AdSense 연결됨:', status.adsense.email, status.adsense.account_id)
+   * }
+   * if (status.admob.is_connected) {
+   *     console.log('AdMob 연결됨:', status.admob.account_id, status.admob.publisher_id)
    * }
    * ```
    */