connectbase-client 1.12.0 → 3.0.0

package/CHANGELOG.md

@@ -3,6 +3,138 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.0.0] - 2026-04-28 — BREAKING
+
+게임 서버 mechanism-only 재설계. ConnectBase 가 박아두던 게임 룰 (파티/로비/랭킹/매치메이킹/
+killcam/highlight) 을 모두 제거하고, primitive (`cb.game.matchqueue`, `cb.game.leaderboard`,
+`cb.game.scripts`) + 사용자 Lua 로 대체. 1:1 마이그레이션은 [MIGRATION_v3.md](../../../docs/sdk/MIGRATION_v3.md).
+
+### Removed (BREAKING)
+
+- **Lobby**: `listLobbies`, `createLobby`, `getLobby`, `joinLobby`, `leaveLobby`, `toggleReady`,
+  `startGame`, `kickPlayer`, `updateLobby`, `sendLobbyChat`, `invitePlayer`, `acceptInvite`,
+  `declineInvite`, `getPlayerInvites` 메서드 + 관련 타입 (`LobbyInfo`, `CreateLobbyRequest`,
+  `UpdateLobbyRequest`, `LobbyInvite`)
+- **Party**: `createParty`, `joinParty`, `acceptPartyInvite`, `declinePartyInvite`,
+  `leaveParty`, `kickFromParty`, `inviteToParty`, `getParty`, `getMyParties`, `setReady`,
+  `setPartyMetadata`, `getPartyInvites`, `sendPartyChat` + `PartyInfo`, `PartyInvite`
+- **Matchmaking**: `joinQueue`, `leaveQueue`, `getMatchStatus` + `JoinQueueRequest`,
+  `MatchmakingTicket`
+- **Ranking**: `getLeaderboard`, `getPlayerStats`, `getPlayerRank` + `LeaderboardEntry` (구
+  player_id/rating/tier/wins/losses 시그니처. 신규 `LeaderboardScoreEntry` 가 대체).
+- **Killcam/Highlight**: `cb.game.replay.killcam(...)`, `cb.game.replay.highlights(...)`
+  관련 endpoint 가 백엔드에서 제거되어 SDK 호출 시 404. 사용자가 `cb.game.replay.download`
+  로 raw frame 받아 클라/Lua 에서 직접 처리.
+
+### Added — v3 primitive
+
+- **Matchqueue** (`cb.game.matchqueue.*` → `enqueueMatch / listMatchqueue / cancelMatch`):
+  rating/region 등 attributes 는 free-form. 매칭 알고리즘은 사용자 Lua 가 list → notify.
+- **Leaderboard** (`submitScore / getTopScores / getMemberRank / getRankAround / resetLeaderboard / removeFromLeaderboard`):
+  ELO/티어/시즌 박지 않음. 시즌은 key suffix (`ranks:2026q2`) 로 분리, 점수 공식은 Lua.
+- **Scripts** (`uploadScript / listScripts / getScript / listScriptVersions /
+  activateScript / rollbackScript / disableScript`): Lua 스크립트 영속 메타 + 버전 + hot reload.
+- 신규 타입: `MatchqueueTicket`, `MatchqueueListResponse`, `LeaderboardScoreEntry`,
+  `LeaderboardListResponse`, `ScriptMeta`, `ScriptVersion`, `ScriptListResponse`,
+  `ScriptVersionListResponse`, `ScriptDetailResponse`.
+
+### Backend 영향
+
+- game-server v3 부터 `/v1/game/:appID/matchqueue/:key/*`, `/leaderboards/:key/*`,
+  `/scripts/*` 라우트가 유일한 게임 메커니즘 endpoint. lobby/party/ranking/matchmaking
+  엔드포인트는 모두 404.
+- 자세한 변경: [`docs/sdk/MIGRATION_v3.md`](../../../docs/sdk/MIGRATION_v3.md),
+  [`docs/game-server/RECIPES.md`](../../../docs/game-server/RECIPES.md).
+
+### Migration 요약
+
+```ts
+// Before (v2.x)
+await cb.game.matchmaking.join({ mode: "ranked", rating: 1500 })
+await cb.game.ranking.submit({ leaderboard: "elo", score: 2150 })
+
+// After (v3.0)
+await cb.game.enqueueMatch(appId, "ranked", userId, { rating: 1500 })
+await cb.game.submitScore(appId, "elo", userId, 32, "incr")
+```
+
+## [2.0.0] - 2026-04-27 — BREAKING
+
+Realtime presence/typing 단일화의 최종 단계. 1.13 deprecation 단계를 건너뛰고 즉시
+deprecated 코드를 제거. presence/typing 의 단일 SoT 는 `cb.realtime.*`.
+
+### Removed (BREAKING)
+
+- **`cb.database.setPresence(status, device, metadata)`** — 코드 자체 제거. 호출 시 `TypeError`.
+- **`cb.database.subscribePresence(userIds, callback)`** — 코드 자체 제거.
+- **`DatabasePresenceState`** type — `PresenceInfo` (from `'./realtime'`) 사용.
+- 1.13 에서 추가됐던 deprecation `console.warn` 헬퍼도 함께 제거 (필요 없음).
+
+### Migration
+
+```ts
+// Before
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen)
+})
+
+// After
+await cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+const unsub = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen)
+})
+```
+
+자세한 가이드: [MIGRATION-v2.md](./MIGRATION-v2.md). 필드 차이는 `user_id`→`userId`,
+`last_seen` (ISO) → `lastSeen` (epoch ms), `'busy'` 상태 추가.
+
+### Server-side
+
+데이터 서버 측 presence/typing 코드도 함께 제거되었습니다. `presence_set` / `presence_subscribe`
+/ `typing_*` 메시지를 데이터 서버 WebSocket 으로 보내면 `USE_SOCKET_SERVER` 에러가 반환됩니다.
+
+## [1.13.0] - 2026-04-27
+
+Realtime presence/typing 단일화 — `cb.database.setPresence` / `cb.database.subscribePresence`
+는 v2.0.0 에서 제거됩니다. 신규 코드는 `cb.realtime.*` 를 사용하세요. 자세한 마이그레이션은
+[MIGRATION-v2.md](./MIGRATION-v2.md) 참고.
+
+### Deprecated
+
+- **`cb.database.setPresence(status, device, metadata)`** → `cb.realtime.setPresence(status, { device, metadata })`
+- **`cb.database.subscribePresence(userIds, onPresence)`** → `cb.realtime.subscribePresence(userId, handler)` 또는
+  `cb.realtime.onPresenceChange(handler)` (다중 사용자 일괄 수신).
+- **`DatabasePresenceState`** type → `PresenceInfo` (from `'./realtime'`).
+  - 필드 네이밍: `user_id` → `userId`, `last_seen` (ISO) → `lastSeen` (epoch ms 숫자).
+  - 상태값: `'busy'` 추가 (PresenceInfo 만 지원).
+
+호출 시 개발 환경(`process.env.NODE_ENV !== 'production'`)에서 `console.warn` 이 1회 출력됩니다.
+런타임 동작은 1.12.x 와 동일합니다 (이번 버전은 deprecate 만, 코드 제거는 v2.0.0).
+
+### Changed
+
+- **WebSocket URL 기본값** `cb.database.connectRealtime` 의 기본 endpoint 가
+  `/v1/realtime/ws` → `/v1/database/realtime/ws` 로 변경. 기존 경로는 30일간 alias 로
+  유지되며 응답에 `Sunset` (RFC 8594) + `X-Deprecated-Endpoint` 헤더가 부착됩니다.
+  명시적으로 `dataServerUrl` 을 지정한 경우 자동 변환은 하지 않습니다 (Hyrum's Law 준수).
+
+### Migration
+
+```ts
+// Before (1.12.x)
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen) // ISO string
+})
+
+// After (1.13+, 권장 — v2 호환)
+cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+const unsubscribe = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen) // epoch ms number
+})
+```
+
 ## [1.12.0] - 2026-04-26
 
 Analytics 조회 정렬 옵션 정합성 수정 — `VisitorListOptions.sort_by` 의 TypeScript

package/MIGRATION-v2.md

@@ -0,0 +1,149 @@
+# Migration to v2.0.0 — Presence/Typing 단일화
+
+> 작성일: 2026-04-27
+> 대상 버전: 1.12.x → 2.0.0 (1.13 deprecation 단계 생략, 즉시 제거)
+> 영향: `cb.database.setPresence`, `cb.database.subscribePresence`, `DatabasePresenceState`, WebSocket URL
+
+본 문서는 v1.12.x 이전에서 v2.0.0 으로 업그레이드할 때 필요한 변경 사항을 안내합니다.
+v2.0.0 에서 데이터베이스 측 presence/typing API 가 코드에서 완전히 제거되었습니다
+(호출 시 `TypeError`). presence/typing 의 단일 SoT 는 `cb.realtime.*` 입니다.
+
+## 1. 책임 경계 변경
+
+| 기능 | v1.12.x | v2.0.0 |
+|------|---------|--------|
+| presence 상태 설정/조회/구독 | `cb.database` / `cb.realtime` 양쪽 | `cb.realtime` 만 |
+| typing 상태 | `cb.database` | `cb.realtime` 만 |
+| DB 변경 구독 | `cb.database.connectRealtime` | (변경 없음) |
+| WebSocket URL (DB) | `/v1/realtime/ws` | `/v1/database/realtime/ws` |
+
+## 2. setPresence 마이그레이션
+
+### Before (v1.12.x)
+
+```ts
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+```
+
+### After (v1.13+ / v2)
+
+```ts
+await cb.realtime.setPresence('online', {
+  device: 'web',
+  metadata: { nickname: '홍길동' }
+})
+```
+
+**차이점**
+
+- `cb.realtime.setPresence` 는 `Promise<void>` 를 반환합니다 (기존은 동기 void).
+- `device` 와 `metadata` 가 두 번째 객체 파라미터의 옵션 필드입니다.
+- 상태값에 `'busy'` 가 추가되어 있습니다 (`'online' | 'away' | 'busy' | 'offline'`).
+
+## 3. subscribePresence 마이그레이션
+
+### Before (v1.12.x)
+
+```ts
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen) // string ISO
+})
+```
+
+### After (옵션 1 — 단일 사용자별 구독)
+
+```ts
+const unsub1 = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen) // number (epoch ms)
+})
+const unsub2 = await cb.realtime.subscribePresence('user2', (info) => {
+  console.log(info.userId, info.status, info.eventType) // join/leave/update
+})
+
+// 정리
+unsub1()
+unsub2()
+```
+
+### After (옵션 2 — 앱 전체 변경 일괄 수신)
+
+```ts
+const unsub = cb.realtime.onPresenceChange((info) => {
+  // 모든 사용자의 변경 이벤트가 한 콜백으로 전달됨
+  if (['user1', 'user2'].includes(info.userId)) {
+    console.log(info.userId, info.status)
+  }
+})
+```
+
+**차이점**
+
+| 필드 | v1.12 (`DatabasePresenceState`) | v1.13+ (`PresenceInfo`) |
+|------|-------------------------------|-----------------------|
+| ID | `user_id` (snake) | `userId` (camel) |
+| 마지막 활동 | `last_seen: string` (ISO) | `lastSeen: number` (epoch ms) |
+| 상태 | `'online' \| 'away' \| 'offline'` | `'online' \| 'away' \| 'busy' \| 'offline'` |
+| 이벤트 타입 | (없음) | `eventType?: 'join' \| 'leave' \| 'update'` |
+
+### 변환 헬퍼 (마이그레이션 보조)
+
+기존 `DatabasePresenceState` 모양으로 데이터를 가공하던 코드를 점진적으로 옮길 때 도움이
+되도록, v1 호환 형태(snake_case · ISO 문자열) 로 변환하는 헬퍼 예제. v2.0.0 에서는
+`DatabasePresenceState` type 이 제거되었으므로 inline 타입으로 정의한다.
+
+```ts
+import type { PresenceInfo } from 'connectbase-client'
+
+interface LegacyPresenceState {
+  user_id: string
+  status: 'online' | 'away' | 'offline'
+  last_seen: string
+  device?: string
+  metadata?: Record<string, unknown>
+}
+
+function fromPresenceInfo(info: PresenceInfo): LegacyPresenceState {
+  return {
+    user_id: info.userId,
+    status: info.status === 'busy' ? 'away' : info.status,
+    last_seen: new Date(info.lastSeen).toISOString(),
+    device: info.device,
+    metadata: info.metadata,
+  }
+}
+```
+
+## 4. typing 마이그레이션 (있는 경우)
+
+`cb.database` 에는 공개된 typing 메서드가 없으므로 추가 마이그레이션은 불필요합니다.
+`cb.realtime.startTyping(roomId)` / `cb.realtime.stopTyping(roomId)` /
+`cb.realtime.onTypingChange(roomId, handler)` 를 그대로 사용하세요.
+
+## 5. WebSocket URL 변경
+
+```ts
+await cb.database.connectRealtime({
+  accessToken: 'xxx',
+  dataServerUrl: 'https://data.connectbase.world',
+})
+// SDK 는 자동으로 /v1/database/realtime/ws 로 연결 (v1.13+).
+// 사용자가 dataServerUrl 의 host:port 만 지정하면 path 는 SDK 가 결정.
+```
+
+옛 경로(`/v1/realtime/ws`) 는 v2.0.0 과 함께 서버에서도 제거되었습니다. 사용자 측
+firewall/proxy 에 `/v1/database/realtime/` 경로 허용 규칙이 있는지 확인하세요.
+
+## 6. 런타임 동작 차이
+
+- **v1.12.x**: 두 API 모두 동작.
+- **v2.0.0**: `cb.database.setPresence` / `subscribePresence` 호출 시 `TypeError` (메서드 미존재).
+
+## 7. 자동 마이그레이션 (codemod)
+
+향후 별도 codemod 스크립트가 제공될 예정입니다. 우선은 위 가이드에 따라 수동 변경을
+권장합니다 (필드 네이밍/시그니처 차이가 있어 수동 검토가 안전).
+
+## 8. 문의
+
+- 이슈: GitHub Issues
+- 디스코드: 공식 채널의 `#sdk` 룸

package/README.md

@@ -708,6 +708,29 @@ await subscription.unsubscribe()
 await cb.realtime.disconnect()
 ```
 
+#### Presence / Typing
+
+Presence(온라인 상태) 와 typing(입력 중 표시) 은 `cb.realtime.*` 가 단일 SoT 입니다.
+v2.0.0 에서 `cb.database.setPresence` / `subscribePresence` 는 제거되었습니다.
+v1.x 에서 마이그레이션은 [MIGRATION-v2.md](./MIGRATION-v2.md) 참고.
+
+```typescript
+// 본인 온라인 상태 publish
+await cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+
+// 다른 사용자 상태 구독
+const unsub = await cb.realtime.subscribePresence('user-id', (info) => {
+  console.log(info.userId, info.status, info.eventType) // join | leave | update
+})
+
+// 룸 단위 typing indicator
+await cb.realtime.startTyping('room-id')
+await cb.realtime.stopTyping('room-id')
+const unsubTyping = await cb.realtime.onTypingChange('room-id', (typing) => {
+  console.log(typing.users) // 현재 입력 중인 사용자 ID 목록
+})
+```
+
 #### AI Streaming
 
 Real-time AI text generation using Gemini API through WebSocket.