connectbase-client 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -3,6 +3,86 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [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 예제 타입 회귀 수정
+
+README 의 `cb.database.batch()` / `cb.database.transaction()` 예제가 구 시그니처
+(`table: 'string'`) 를 사용해 `tsc --noEmit` 에서 `TS2353` 발생하던 문제 수정.
+
+- `table:` → `table_id:` (UUID, 실제 `BatchOperation` 타입과 일치)
+- 3.12+ 의 `success:false` throw 동작 반영 — try/catch 패턴 명시
+
+코드 변경은 없음. README 만 갱신.
+
 ## [3.13.0] - 2026-05-13
 
 ### Removed — `PlatformIssueDetail.triage_summary` / `triaged_at` 필드

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
@@ -587,26 +599,41 @@ nearby.results.forEach(place => {
 
 #### Batch & Transactions
 
+`table_id` 는 항상 UUID. 콘솔/REST 로 생성한 테이블의 UUID 를 그대로 사용한다.
+
+v3.12+ 부터 server 가 부분 실패(`success: false`)를 응답하면 SDK 가 첫 실패 op 의
+error 메시지로 throw 한다 — silent success 회귀 방지 차원. 호출자는 try/catch 로 감싼다.
+
 ```typescript
 // Batch: atomic multi-table operations
-await cb.database.batch([
-  { type: 'create', table: 'orders', data: { product: 'A', qty: 1 } },
-  { type: 'update', table: 'inventory', doc_id: 'item-a', operators: {
-    qty: { type: 'increment', value: -1 }
-  }},
-  { type: 'update', table: 'stats', doc_id: 'daily', operators: {
-    order_count: { type: 'increment', value: 1 },
-    last_order: { type: 'serverTimestamp' }
-  }}
-])
+try {
+  const result = await cb.database.batch([
+    { type: 'create', table_id: ORDERS_TABLE_ID, data: { product: 'A', qty: 1 } },
+    { type: 'update', table_id: INVENTORY_TABLE_ID, doc_id: 'item-a', operators: {
+      qty: { type: 'increment', value: -1 }
+    }},
+    { type: 'update', table_id: STATS_TABLE_ID, doc_id: 'daily', operators: {
+      order_count: { type: 'increment', value: 1 },
+      last_order: { type: 'serverTimestamp' }
+    }}
+  ])
+  // result.success, result.results[i].{success, doc_id, error}
+} catch (e) {
+  // RLS 거부 / 검증 실패 / table_id 오타 등 — 전체 batch 가 atomic 하게 롤백
+  console.error('batch failed:', (e as Error).message)
+}
 
 // Transaction: read-then-write with ACID guarantees
-await cb.database.transaction(
-  [{ table: 'accounts', doc_id: 'user-1', alias: 'sender' }],
-  [{ type: 'update', table: 'accounts', doc_id: 'user-1', operators: {
-    balance: { type: 'increment', value: -100 }
-  }}]
-)
+try {
+  await cb.database.transaction(
+    [{ table_id: ACCOUNTS_TABLE_ID, doc_id: 'user-1', alias: 'sender' }],
+    [{ type: 'update', table_id: ACCOUNTS_TABLE_ID, doc_id: 'user-1', operators: {
+      balance: { type: 'increment', value: -100 }
+    }}]
+  )
+} catch (e) {
+  console.error('transaction failed:', (e as Error).message)
+}
 ```
 
 #### Populate (Relation Query / JOIN)