connectbase-client 3.13.1 → 3.14.1

package/CHANGELOG.md

@@ -3,6 +3,102 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.14.1] - 2026-05-14
+
+### Fixed — `cb.game.*` primitive 호스트 라우팅 회귀 (v3.0.0 이후 잠복)
+
+NJB 측 deleteScript / deactivateScript 404 보고 (2026-05-14) 로 발견. v3.0.0 BREAKING 에서
+matchqueue / leaderboard / scripts primitive 메서드 16개가 `this.http.*` (기본 baseUrl
+= core-server, `api.connectbase.world`) 를 거치도록 잘못 wired 되어 game-server
+(`game.connectbase.world`) 로 라우팅되지 않고 404 회귀. NJB 는 v3.9.0 부터 `uploadScript`
+회귀를 raw fetch 로 우회 중이었음 (apps/game/scripts/upload-lua.mjs 참고).
+
+수정: `GameAPI` 내부 `gameFetch` private helper 도입. `${this.gameServerUrl}${path}` 기준
+fetch + 표준 `getHeaders()` (X-Public-Key / Bearer) + 서버 응답 `{ error }` → `ApiError.code`
+surface + 204/non-JSON 응답을 `undefined` 로 처리. 영향받은 메서드:
+
+- **scripts (8)**: `uploadScript` / `listScripts` / `getScript` / `listScriptVersions` /
+  `activateScript` / `rollbackScript` / `deactivateScript` / `deleteScript`
+- **matchqueue (3)**: `enqueueMatch` / `listMatchqueue` / `cancelMatch`
+- **leaderboard (6)**: `submitScore` / `getTopScores` / `getMemberRank` /
+  `getRankAround` / `resetLeaderboard` / `removeFromLeaderboard`
+
+기존에 raw fetch 로 우회 중이던 통합 코드는 SDK 본 메서드로 회귀해도 무방 (4xx/5xx 시
+`ApiError` 로 throw 되며 status/code 분기는 동일하게 작동).
+
+### Added — 회귀 가드 테스트
+
+- `test/game-host-routing.test.ts` — 17개 메서드 전체가 `game.*` 호스트로 라우팅되는지
+  fetch mock 으로 단언. 동일 회귀 재발 방지.
+
+## [3.14.0] - 2026-05-14
+
+### Added — `GameError` 클래스 + `createRoom` 응답 메타
+
+- 신규 export: `GameError` (extends `Error`) — game-server 의 `error` 메시지를 일관된
+  인스턴스로 surface. `.code`, `.phase`, `.feature`, `.originClientId`, `.requested`,
+  `.available` 모두 노출. `instanceof GameError` 로 UI 분기 가능.
+- 신규 export: `GameErrorCode` literal union — `'SCRIPT_NOT_FOUND' | 'NO_ACTION_HANDLER'
+  | 'FEATURE_DISABLED' | 'SCRIPT_ERROR' | 'SCRIPT_TIMEOUT' | 'RATE_LIMITED' |
+  'QUOTA_EXCEEDED' | 'TIMEOUT' | 'UNKNOWN' | (string & {})`.
+- 신규 export: `CreateRoomResult` 타입 — `{ roomId, state, scriptName?, scriptVersion? }`.
+- 신규 메서드: `GameRoom.createRoomDetailed(config)` + `GameRoomTransport.createRoomDetailed(config)`
+  — server 가 attach 한 lua script 의 이름/버전을 client 가 즉시 검증할 수 있게 응답에 포함.
+- 신규 getter: `room.scriptName` / `room.scriptVersion` (`GameRoom` + `GameRoomTransport`)
+  — 마지막 `createRoom` 응답의 메타. `joinRoom`/`leaveRoom`/`disconnect` 시 reset.
+- 기존 `createRoom(config)` 의 시그니처는 그대로 (호환). 내부적으로 `createRoomDetailed`
+  를 호출하고 `.state` 만 반환.
+- `onError` 콜백 시그니처가 `Event | ErrorMessage` → `Event | GameError` 로 변경 (호환:
+  `ErrorMessage` 의 모든 필드가 `GameError` 인스턴스에 동일하게 surface 됨).
+
+### Changed (BREAKING) — `disableScript` rename + `deleteScript` 신규
+
+server 측 `DELETE /v1/game/:appID/scripts/:name` 의 의미가 **Disable → hard-delete** 로
+변경된 것에 대응:
+
+- `GameAPI.disableScript(appId, name)` **제거**. 대체: `GameAPI.deactivateScript(appId, name)`
+  — `POST /scripts/:name/deactivate` 호출 (코드/버전 보존, 재활성화 가능).
+- `GameAPI.deleteScript(appId, name)` **신규** — `DELETE /scripts/:name` 호출 (메타 + 모든
+  버전 영구 제거, 복구 불가).
+
+### Fixed — `error` 메시지 분류 메타 손실 회귀
+
+이전엔 모든 `reject(new Error(msg.data.message))` 로 server 의 `code`/`phase`/`feature`/
+`origin_client_id`/`requested`/`available` 가 손실되어 SDK 사용자가 UI 분기를 만들 수
+없었다 (platform-issue 019e21dd, NJB 2026-05-13). 이제 `GameError` 인스턴스로 reject
+되어 모든 메타가 보존된다.
+
+### Migration
+
+```ts
+// Before
+import { ErrorMessage } from 'connectbase-client'
+room.on('error', (err) => {
+    if ((err as ErrorMessage).code === 'FEATURE_DISABLED') { /* ... */ }
+})
+await cb.game.disableScript(appId, 'old-script')
+
+// After
+import { GameError } from 'connectbase-client'
+room.on('error', (err) => {
+    if (err instanceof GameError) {
+        if (err.code === 'SCRIPT_NOT_FOUND') console.error('candidates:', err.available)
+        if (err.code === 'NO_ACTION_HANDLER') console.error('handler for', err.phase, 'undefined')
+        if (err.code === 'FEATURE_DISABLED') console.error('feature off:', err.feature)
+        if (err.originClientId) console.warn('error from other player:', err.originClientId)
+    }
+})
+await cb.game.deactivateScript(appId, 'old-script')  // 비활성화 (코드 보존)
+await cb.game.deleteScript(appId, 'really-old')      // 영구 삭제 (신규)
+
+// createRoom 응답 검증 패턴 (NJB regression 가드)
+const { state, scriptName, scriptVersion } = await room.createRoomDetailed({ scriptName: 'njb-main' })
+if (scriptName !== 'njb-main') {
+    throw new Error(`script attach mismatch: expected njb-main got ${scriptName}`)
+}
+console.log('attached', scriptName, 'v', scriptVersion)
+```
+
 ## [3.13.1] - 2026-05-13
 
 ### Documentation — README batch/transaction 예제 타입 회귀 수정

package/README.md

@@ -65,8 +65,20 @@ gameClient
 await gameClient.connect()
 const state = await gameClient.createRoom({
   maxPlayers: 4,
-  tickRate: 64
+  tickRate: 64,
+  scriptName: 'my-script', // Optional: attach a lua script (must be pre-uploaded + active)
 })
+
+// 3.14+ — Attached script 의 이름/버전을 검증하고 싶으면 createRoomDetailed 사용
+import { GameError } from 'connectbase-client'
+try {
+  const r = await gameClient.createRoomDetailed({ scriptName: 'my-script' })
+  console.log('attached', r.scriptName, 'v', r.scriptVersion)
+} catch (e) {
+  if (e instanceof GameError && e.code === 'SCRIPT_NOT_FOUND') {
+    console.error('script missing — candidates:', e.available)
+  }
+}
 ```
 
 ## Features