connectbase-client 3.2.1 → 3.3.1

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.3.1] - 2026-04-30
+
+### Fixed — Docs
+
+3.3.0 publish 직후 SDK 감사에서 `README.md` 의 `### Game Server` 섹션에 신규 API
+`cb.game.config` 가 누락된 것을 발견. npm 페이지의 사용자 1차 문서 정합성을 위해
+patch release 로 보강.
+
+- README 의 `## API Reference > ### Game Server` 아래에 `#### cb.game.config — Feature
+  Opt-in (v3.1+, SDK 3.3.0+)` 섹션 추가 — get/set/enable/disable 4개 메서드 시그니처,
+  partial PATCH 의미, HTTP 응답 코드 표 (403 / 429 / 402), OPT_IN.md cross-link.
+- 코드 동작 변화 없음. README/CHANGELOG 만 수정.
+
+## [3.3.0] - 2026-04-30
+
+### Added — `cb.game.config` (게임 기능 opt-in 토글)
+
+게임 서버 v3.1 의 7개 기능 (matchqueue / leaderboard / entity / scripts / voice / replay /
+spectator) 이 모두 앱 단위 명시적 opt-in 정책으로 전환됨에 따라, 콘솔 / 외부 도구가
+토글 상태를 조회/변경할 수 있는 SDK 헬퍼 신규 추가.
+
+- **`cb.game.config.get(appId?)`** — 현재 7개 토글 상태 + `legacy_defaults` 플래그.
+  row 가 없는 기존 앱은 모든 기능 ON 상태로 응답 (서비스 단절 방지). `legacy_defaults=true`
+  를 받으면 backfill 권장.
+- **`cb.game.config.set(appId, patch)`** / **`cb.game.config.set(patch)`** — partial
+  update. 보낸 필드만 갱신, 나머지는 보존. PATCH 직후 game-server 캐시는 NATS
+  publish 로 즉시 무효화 (또는 30s TTL).
+- **`cb.game.config.enable(appId, feature)`** / **`disable(appId, feature)`** —
+  단일 토글 편의 wrapper.
+
+```ts
+const cfg = await cb.game.config.get(appId)
+if (!cfg.matchqueue_enabled) {
+  await cb.game.config.set(appId, { matchqueue_enabled: true, leaderboard_enabled: true })
+}
+```
+
+신규 앱은 모든 기능 OFF 가 기본값. 사용 안 하는 앱은 noisy-neighbor / 의도치 않은
+quota 소비에서 격리됨.
+
+자세한 정책: [docs/game-server/OPT_IN.md](https://github.com/connectbase-world/connectbase/blob/release/docs/game-server/OPT_IN.md)
+
+### Behavior — 비활성 기능 호출 시 응답 변화
+
+본 버전부터, 비활성 feature 의 HTTP 호출은 **HTTP 403 + `{error: "feature_disabled", feature, hint}`**
+를 반환. 기존 SDK 호출 코드는 catch 에서 status 403 + error 코드를 분기해 사용자에게
+"콘솔에서 켜주세요" 메시지를 표시하는 게 권장됩니다.
+
 ## [3.2.1] - 2026-04-29
 
 ### Fixed — Docs

package/README.md

@@ -229,6 +229,43 @@ curl -X PUT "https://api.connectbase.world/v1/apps/{appID}/storages/webs/{storag
 
 ### Game Server
 
+#### `cb.game.config` — Feature Opt-in (v3.1+, SDK 3.3.0+)
+
+The game server's 7 features (`matchqueue` / `leaderboard` / `entity` / `scripts` /
+`voice` / `replay` / `spectator`) are **explicit opt-in per app** as of v3.1
+(2026-04-30). Disabled features return HTTP **403 `feature_disabled`**.
+New apps default to all-OFF; existing apps without a config row fall back to
+all-ON for compatibility.
+
+```typescript
+// Inspect current toggles
+const cfg = await cb.game.config.get(appId)
+// → { matchqueue_enabled, leaderboard_enabled, entity_enabled, scripts_enabled,
+//     voice_enabled, replay_enabled, spectator_enabled }
+
+// Partial update — only the keys you send are applied; others are preserved.
+await cb.game.config.set(appId, {
+  matchqueue_enabled: true,
+  leaderboard_enabled: true,
+})
+
+// Single-toggle convenience wrappers
+await cb.game.config.enable(appId, 'matchqueue_enabled')
+await cb.game.config.disable(appId, 'voice_enabled')
+```
+
+The PATCH publishes a NATS invalidation so game-server caches drop the entry
+immediately (30s TTL is the safety net).
+
+| HTTP code | Body `error` | Meaning | Client action |
+|-----------|--------------|---------|---------------|
+| **403** | `feature_disabled` | Feature is not enabled for this app | Toggle via console or `cb.game.config.set(...)` |
+| **429** | `cap_exceeded` | Per-app cardinality cap reached | Remove old rows or ask the operator to raise the cap env |
+| **402** | `quota_exceeded` | Plan limit reached on a write route | Upgrade plan |
+
+See [docs/game-server/OPT_IN.md](https://github.com/connectbase-world/connectbase/blob/release/docs/game-server/OPT_IN.md)
+for the full policy.
+
 #### GameRoom
 
 The main class for real-time game communication.