connectbase-client 1.12.0 → 3.0.0

package/dist/index.mjs

@@ -1613,41 +1613,6 @@ var DatabaseAPI = class {
       }
     };
   }
-  /**
-   * 프레즌스 상태 설정
-   */
-  setPresence(status, device, metadata) {
-    if (this.realtimeState !== "connected") return;
-    this.sendRealtimeMessage({
-      type: "presence_set",
-      request_id: this.generateRequestId(),
-      status,
-      device,
-      metadata
-    });
-  }
-  /**
-   * 프레즌스 구독 (다른 사용자의 온라인 상태 감시)
-   */
-  subscribePresence(userIds, onPresence) {
-    if (this.realtimeState !== "connected") return;
-    this.realtimeHandlers.set("__presence__", {
-      onSnapshot: (docs) => {
-        const states = {};
-        for (const doc of docs) {
-          if (doc.data) {
-            states[doc.id] = doc.data;
-          }
-        }
-        onPresence(states);
-      }
-    });
-    this.sendRealtimeMessage({
-      type: "presence_subscribe",
-      request_id: this.generateRequestId(),
-      user_ids: userIds
-    });
-  }
   /**
    * 실시간 연결 상태 확인
    */
@@ -1689,7 +1654,7 @@ var DatabaseAPI = class {
     this.setRealtimeState("connecting");
     const baseUrl = this.realtimeOptions.dataServerUrl || this.http.getBaseUrl();
     const wsUrl = baseUrl.replace(/^http/, "ws");
-    const url = `${wsUrl}/v1/realtime/ws?access_token=${encodeURIComponent(this.realtimeOptions.accessToken)}`;
+    const url = `${wsUrl}/v1/database/realtime/ws?access_token=${encodeURIComponent(this.realtimeOptions.accessToken)}`;
     return new Promise((resolve, reject) => {
       try {
         this.realtimeWs = new WebSocket(url);
@@ -6609,495 +6574,6 @@ var GameAPI = class {
   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 ====================
-  /**
-   * 매치메이킹 큐에 참가
-   */
-  async joinQueue(req) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/matchmaking/queue`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({
-        game_type: req.gameType,
-        player_id: req.playerId,
-        rating: req.rating,
-        region: req.region,
-        mode: req.mode,
-        party_members: req.partyMembers,
-        metadata: req.metadata
-      })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to join queue: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      ticketId: data.ticket_id,
-      gameType: data.game_type,
-      playerId: data.player_id,
-      status: data.status,
-      createdAt: data.created_at
-    };
-  }
-  /**
-   * 매치메이킹 큐에서 탈퇴
-   */
-  async leaveQueue(ticketId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/matchmaking/queue`, {
-      method: "DELETE",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ ticket_id: ticketId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to leave queue: ${response.statusText}`);
-    }
-  }
-  /**
-   * 매치메이킹 상태 조회
-   */
-  async getMatchStatus(params) {
-    const id = this.appId || "";
-    const searchParams = new URLSearchParams();
-    if (params.ticketId) searchParams.set("ticket_id", params.ticketId);
-    if (params.playerId) searchParams.set("player_id", params.playerId);
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/matchmaking/status?${searchParams}`, {
-      headers: this.getHeaders()
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to get match status: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      ticketId: data.ticket_id,
-      gameType: data.game_type,
-      playerId: "",
-      status: data.status,
-      createdAt: "",
-      waitTime: data.wait_time,
-      matchId: data.match_id,
-      roomId: data.room_id
-    };
-  }
-  // ==================== Lobbies ====================
-  /**
-   * 로비 목록 조회
-   */
-  async listLobbies() {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies`, {
-      headers: this.getHeaders()
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to list lobbies: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return (data.lobbies || []).map((l) => ({
-      id: l.id,
-      name: l.name,
-      hostId: l.host_id,
-      gameType: l.game_type,
-      playerCount: l.player_count,
-      maxPlayers: l.max_players,
-      hasPassword: l.has_password,
-      visibility: l.visibility,
-      region: l.region,
-      settings: l.settings,
-      tags: l.tags,
-      status: l.status,
-      createdAt: l.created_at
-    }));
-  }
-  /**
-   * 로비 생성
-   */
-  async createLobby(req) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({
-        player_id: req.playerId,
-        display_name: req.displayName,
-        name: req.name,
-        game_type: req.gameType,
-        password: req.password,
-        max_players: req.maxPlayers,
-        visibility: req.visibility,
-        region: req.region,
-        settings: req.settings,
-        tags: req.tags
-      })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to create lobby: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      id: data.id,
-      name: data.name,
-      hostId: data.host_id,
-      gameType: data.game_type,
-      playerCount: 1,
-      maxPlayers: data.max_players,
-      hasPassword: !!req.password,
-      visibility: data.visibility,
-      region: data.region,
-      settings: data.settings,
-      tags: data.tags,
-      status: data.status,
-      createdAt: data.created_at
-    };
-  }
-  /**
-   * 로비 상세 조회
-   */
-  async getLobby(lobbyId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}`, {
-      headers: this.getHeaders()
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to get lobby: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      id: data.id,
-      name: data.name,
-      hostId: data.host_id,
-      gameType: data.game_type,
-      playerCount: data.player_count,
-      maxPlayers: data.max_players,
-      hasPassword: data.has_password,
-      visibility: data.visibility,
-      region: data.region,
-      settings: data.settings,
-      tags: data.tags,
-      status: data.status,
-      roomId: data.room_id,
-      members: (data.members || []).map((m) => ({
-        playerId: m.player_id,
-        displayName: m.display_name,
-        role: m.role,
-        team: m.team,
-        ready: m.ready,
-        slot: m.slot,
-        joinedAt: m.joined_at
-      })),
-      createdAt: data.created_at
-    };
-  }
-  /**
-   * 로비 참가
-   */
-  async joinLobby(lobbyId, playerId, displayName, password) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/join`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, display_name: displayName, password })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to join lobby: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return { lobbyId: data.lobby_id };
-  }
-  /**
-   * 로비 퇴장
-   */
-  async leaveLobby(lobbyId, playerId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/leave`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to leave lobby: ${response.statusText}`);
-    }
-  }
-  /**
-   * 레디 상태 토글
-   */
-  async toggleReady(lobbyId, playerId, ready) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/ready`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, ready })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to toggle ready: ${response.statusText}`);
-    }
-  }
-  /**
-   * 게임 시작 (호스트만)
-   */
-  async startGame(lobbyId, hostId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/start`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ host_id: hostId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to start game: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return { roomId: data.room_id };
-  }
-  /**
-   * 플레이어 추방 (호스트만)
-   */
-  async kickPlayer(lobbyId, hostId, targetPlayerId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/kick/${targetPlayerId}`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ host_id: hostId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to kick player: ${response.statusText}`);
-    }
-  }
-  /**
-   * 로비 설정 업데이트 (호스트만)
-   */
-  async updateLobby(lobbyId, req) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}`, {
-      method: "PATCH",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({
-        host_id: req.hostId,
-        name: req.name,
-        max_players: req.maxPlayers,
-        visibility: req.visibility,
-        password: req.password,
-        settings: req.settings,
-        tags: req.tags
-      })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to update lobby: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      id: data.id,
-      name: data.name,
-      hostId: "",
-      gameType: "",
-      playerCount: 0,
-      maxPlayers: data.max_players,
-      hasPassword: false,
-      visibility: data.visibility,
-      region: "",
-      settings: data.settings,
-      tags: data.tags,
-      status: "",
-      createdAt: ""
-    };
-  }
-  /**
-   * 로비 채팅 전송
-   */
-  async sendLobbyChat(lobbyId, playerId, message) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/chat`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, message })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to send chat: ${response.statusText}`);
-    }
-  }
-  /**
-   * 플레이어 초대
-   */
-  async invitePlayer(lobbyId, inviterId, inviteeId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/${lobbyId}/invite`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ inviter_id: inviterId, invitee_id: inviteeId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to invite player: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return {
-      inviteId: data.invite_id,
-      lobbyId: data.lobby_id,
-      lobbyName: data.lobby_name,
-      inviterId: data.inviter_id,
-      inviteeId: data.invitee_id,
-      status: "pending",
-      createdAt: "",
-      expiresAt: data.expires_at
-    };
-  }
-  /**
-   * 초대 수락
-   */
-  async acceptInvite(inviteId, playerId, displayName) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/invites/${inviteId}/accept`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, display_name: displayName })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to accept invite: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return { lobbyId: data.lobby_id };
-  }
-  /**
-   * 초대 거절
-   */
-  async declineInvite(inviteId, playerId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/invites/${inviteId}/decline`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId })
-    });
-    if (!response.ok) {
-      const err = await response.json().catch(() => ({}));
-      throw new Error(err.error || `Failed to decline invite: ${response.statusText}`);
-    }
-  }
-  /**
-   * 플레이어의 받은 초대 목록
-   */
-  async getPlayerInvites(playerId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/lobbies/player/${playerId}/invites`, {
-      headers: this.getHeaders()
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to get invites: ${response.statusText}`);
-    }
-    const data = await response.json();
-    return (data.invites || []).map((inv) => ({
-      inviteId: inv.invite_id,
-      lobbyId: inv.lobby_id,
-      lobbyName: inv.lobby_name,
-      inviterId: inv.inviter_id,
-      inviteeId: "",
-      status: inv.status,
-      createdAt: inv.created_at,
-      expiresAt: inv.expires_at
-    }));
-  }
-  // --- 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`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId, max_size: maxSize || 4 })
-    });
-    if (!response.ok) throw new Error(`Failed to create party: ${response.statusText}`);
-    return response.json();
-  }
-  /**
-   * @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 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`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ player_id: playerId })
-    });
-    if (!response.ok) throw new Error(`Failed to leave party: ${response.statusText}`);
-  }
-  async kickFromParty(partyId, playerId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/kick/${playerId}`, {
-      method: "POST",
-      headers: this.getHeaders()
-    });
-    if (!response.ok) throw new Error(`Failed to kick from party: ${response.statusText}`);
-  }
-  async inviteToParty(partyId, inviterId, inviteeId) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/invite/${inviteeId}`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      body: JSON.stringify({ inviter_id: inviterId })
-    });
-    if (!response.ok) throw new Error(`Failed to invite to party: ${response.statusText}`);
-    return response.json();
-  }
-  async sendPartyChat(partyId, playerId, message) {
-    const id = this.appId || "";
-    const response = await fetch(`${this.gameServerUrl}/v1/game/${id}/parties/${partyId}/chat`, {
-      method: "POST",
-      headers: { ...this.getHeaders(), "Content-Type": "application/json" },
-      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) {
@@ -7127,36 +6603,6 @@ var GameAPI = class {
     const data = await response.json();
     return data.spectators || [];
   }
-  // --- Ranking/Leaderboard API ---
-  // 1.1.0 부터 활성화. 백엔드가 `app_id` + `game_type` 쿼리를 요구하므로 SDK 시그니처에 `gameType` 추가.
-  async getLeaderboard(gameType, top = 100, season = "default") {
-    const id = this.appId || "";
-    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, gameType, season = "default") {
-    const id = this.appId || "";
-    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, gameType, season = "default") {
-    const id = this.appId || "";
-    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}`);
-    return response.json();
-  }
   // --- Voice API ---
   async joinVoiceChannel(roomId, playerId) {
     const id = this.appId || "";
@@ -7247,6 +6693,166 @@ var GameAPI = class {
     }
     return headers;
   }
+  // ─────────────────────────────────────────────────────────────────────
+  // Phase 3 — Matchqueue primitive (mechanism only)
+  //
+  // 매칭 알고리즘 (어떤 ticket 끼리 묶을지) 은 사용자 Lua 가 list → notify 흐름으로
+  // 직접 구현. attributes 는 free-form JSON 으로 rating/region/team_size 등 자유롭게 첨부.
+  // 매칭 완료 시 사용자가 cb.realtime.subscribe(`matchqueue.${appID}.${queueKey}`) 로 수신.
+  //
+  // 자세한 패턴: docs/game-server/RECIPES.md §10
+  // ─────────────────────────────────────────────────────────────────────
+  /**
+   * matchqueue 에 ticket 등록.
+   *
+   * @example
+   * await cb.game.enqueueMatch(appId, "ranked", userId, {
+   *   rating: 1500, region: "asia", team_size: 5,
+   * }, 60)
+   *
+   * @constraints appId/queueKey/ticketId 는 [a-zA-Z0-9_-] 만 허용. ttlSec=0 이면 만료 없음.
+   */
+  async enqueueMatch(appId, queueKey, ticketId, attributes, ttlSec) {
+    return this.http.post(
+      `/v1/game/${appId}/matchqueue/${queueKey}/tickets`,
+      { ticket_id: ticketId, attributes, ttl_sec: ttlSec ?? 0 }
+    );
+  }
+  /**
+   * matchqueue 의 모든 ticket 목록 반환. 사용자 Lua 가 매칭 후보 선별에 사용.
+   *
+   * @example const tickets = await cb.game.listMatchqueue(appId, "ranked")
+   */
+  async listMatchqueue(appId, queueKey) {
+    return this.http.get(
+      `/v1/game/${appId}/matchqueue/${queueKey}`
+    );
+  }
+  /**
+   * 매칭 큐에서 ticket 제거 (예: 사용자가 매칭 취소).
+   */
+  async cancelMatch(appId, queueKey, ticketId) {
+    await this.http.delete(
+      `/v1/game/${appId}/matchqueue/${queueKey}/tickets/${ticketId}`
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // Phase 4 — Leaderboard primitive (mechanism only)
+  //
+  // 시즌은 사용자가 leaderboardKey suffix 로 분리 (예: "ranks:2026q2"). ELO/티어 공식은
+  // 사용자 Lua 가 incrScore 호출로 결과 기록 (RECIPES.md §6 참고).
+  // ─────────────────────────────────────────────────────────────────────
+  /**
+   * leaderboard 점수 기록. mode="set" (기본, overwrite) 또는 "incr" (증감).
+   *
+   * @example
+   * await cb.game.submitScore(appId, "global_elo", userId, 32, "incr")
+   */
+  async submitScore(appId, leaderboardKey, member, score, mode = "set") {
+    return this.http.post(
+      `/v1/game/${appId}/leaderboards/${leaderboardKey}/scores`,
+      { member, score, mode }
+    );
+  }
+  /**
+   * 상위 n 명 조회 (기본 10).
+   */
+  async getTopScores(appId, leaderboardKey, n = 10) {
+    return this.http.get(
+      `/v1/game/${appId}/leaderboards/${leaderboardKey}/top?n=${n}`
+    );
+  }
+  /**
+   * 단일 member 의 rank + score.
+   */
+  async getMemberRank(appId, leaderboardKey, member) {
+    return this.http.get(
+      `/v1/game/${appId}/leaderboards/${leaderboardKey}/members/${member}`
+    );
+  }
+  /**
+   * member 주변 (위 above 명 + 본인 + 아래 below 명) 조회.
+   */
+  async getRankAround(appId, leaderboardKey, member, above = 5, below = 5) {
+    return this.http.get(
+      `/v1/game/${appId}/leaderboards/${leaderboardKey}/around/${member}?above=${above}&below=${below}`
+    );
+  }
+  /**
+   * leaderboard 전체 reset (시즌 종료 시).
+   */
+  async resetLeaderboard(appId, leaderboardKey) {
+    await this.http.delete(`/v1/game/${appId}/leaderboards/${leaderboardKey}`);
+  }
+  /**
+   * 특정 member 만 제거 (계정 삭제 등).
+   */
+  async removeFromLeaderboard(appId, leaderboardKey, member) {
+    await this.http.delete(
+      `/v1/game/${appId}/leaderboards/${leaderboardKey}/members/${member}`
+    );
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // Phase 5 — Lua 스크립트 관리 (메타데이터 + 버전 + hot reload)
+  //
+  // 활성화 시 NATS publish 로 모든 게임 서버 인스턴스가 VM pool 핫 리로드.
+  // ─────────────────────────────────────────────────────────────────────
+  /**
+   * 새 스크립트 버전 업로드 (latest+1). idempotent — 동일 hash 면 새 버전 만들지 않음.
+   *
+   * @example
+   * await cb.game.uploadScript(appId, "ranked_br", fs.readFileSync("./ranked.lua", "utf-8"))
+   */
+  async uploadScript(appId, name, code) {
+    return this.http.post(
+      `/v1/game/${appId}/scripts`,
+      { name, code }
+    );
+  }
+  /**
+   * app 의 모든 스크립트 메타데이터 목록.
+   */
+  async listScripts(appId) {
+    return this.http.get(`/v1/game/${appId}/scripts`);
+  }
+  /**
+   * 단일 스크립트 메타 + active version code.
+   */
+  async getScript(appId, name) {
+    return this.http.get(`/v1/game/${appId}/scripts/${name}`);
+  }
+  /**
+   * 단일 스크립트의 모든 버전 이력.
+   */
+  async listScriptVersions(appId, name) {
+    return this.http.get(
+      `/v1/game/${appId}/scripts/${name}/versions`
+    );
+  }
+  /**
+   * 특정 버전 활성화 (hot reload 자동). version=0 또는 미지정 → latest 활성화.
+   */
+  async activateScript(appId, name, version) {
+    return this.http.post(
+      `/v1/game/${appId}/scripts/${name}/activate`,
+      { version: version ?? 0 }
+    );
+  }
+  /**
+   * 직전 active 버전으로 롤백 (hot reload 자동).
+   */
+  async rollbackScript(appId, name) {
+    return this.http.post(
+      `/v1/game/${appId}/scripts/${name}/rollback`,
+      {}
+    );
+  }
+  /**
+   * 스크립트 비활성화 (status=disabled). 코드/버전은 보존.
+   */
+  async disableScript(appId, name) {
+    await this.http.delete(`/v1/game/${appId}/scripts/${name}`);
+  }
 };
 
 // src/api/ads.ts