connectbase-client 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [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
+
+`cb.endpoint.url(label, path)` 의 README/JSDoc 예제와 CHANGELOG `[3.2.0]` 설명을
+ConnectBase 프록시 인증 모델에 맞춰 정정. 코드 동작 변화 없음 (JSDoc / README /
+CHANGELOG 만 수정).
+
+- 3.2.0 의 `<img src={cb.endpoint.url(...)}>` / `new WebSocket(cb.endpoint.url(...))`
+  예제는 실제로는 401 — `/v1/proxy/:label/*` 가 `X-Public-Key` 헤더를 강제하고
+  쿼리 파라미터 폴백이 없어, 커스텀 헤더를 못 보내는 브라우저 네이티브 API
+  (`<img>`, native `WebSocket`, `<script src>`, `EventSource`) 는 인증 자체가
+  불가능. 잘못된 시연 코드를 제거.
+- 정정된 사용 사례:
+  - **이미지 렌더링**: `cb.endpoint.call(...)` 로 받아
+    `URL.createObjectURL(await res.blob())` 패턴 사용. 영구 URL 이 필요하면
+    `cb.storage.uploadByPath` 로 업로드.
+  - **URL 전달**: Service Worker / 백엔드 워커 / 커스텀 fetch wrapper 처럼 호출자가
+    `X-Public-Key` 헤더를 직접 부착할 수 있는 환경.
+  - **로깅·디버깅**: 라벨 → 최종 URL 매핑 확인.
+- `EndpointAPI` 클래스 / `cb.endpoint.{call,url,pollUntil}` 동작은 3.2.0 과 동일.
+
 ## [3.2.0] - 2026-04-29
 
 ### Added — Endpoint API 헬퍼 (`pollUntil` / `url`)
@@ -16,10 +73,13 @@ ComfyUI × 웹스토리지 같은 e2e 통합 패턴 (작업 제출 → 폴링
   "작업 제출 → 폴링" 패턴 전용. `predicate` 가 값을 반환할 때까지 반복 호출,
   HTTP 5xx/네트워크 오류는 재시도, 4xx 는 즉시 reject, `AbortSignal`/`timeoutMs`
   지원. `parse: "json" | "text" | "none"` 으로 본문 파싱 방식 선택.
-- **`cb.endpoint.url(label, path)`** — 라벨 + path 의 최종 호출 URL 을 조립해서
-  반환. WebSocket / `<img src>` / `new Image()` 같이 SDK 의 `call()` 이 아닌
-  직접 호출이 필요할 때. `X-Public-Key` 는 자동 주입되지 않으므로 모델 서버가
-  자체 토큰으로 인증을 별도 처리해야 함 (ConnectBase 는 dumb pipe).
+- **`cb.endpoint.url(label, path)`** — 라벨 + path 의 최종 호출 URL
+  (`${baseUrl}/v1/proxy/${label}${path}`) 만 조립해서 반환. URL 을 Service
+  Worker / 백엔드 워커로 넘기거나 로깅·디버깅 용도. ⚠️ `<img src>` / 네이티브
+  `WebSocket` / `<script src>` / `EventSource` 처럼 커스텀 헤더를 못 보내는
+  브라우저 API 에 직접 넘기면 401 — ConnectBase 프록시는 항상 `X-Public-Key`
+  헤더를 요구하고 쿼리 파라미터 폴백이 없음. 그 경우엔 `call()` 로 받아
+  `URL.createObjectURL(await res.blob())` 패턴 사용.
 - 신규 export: `PollUntilOptions` 타입.
 
 ### Docs

package/README.md

@@ -929,23 +929,41 @@ const filename = await cb.endpoint.pollUntil<string>(
 
 #### `cb.endpoint.url(label, path): string`
 
-Returns the assembled call URL (`${baseUrl}/v1/proxy/${label}${path}`) for cases
-where the SDK's `call()` doesn't fit — `<img src>`, `new Image()`, native
-`WebSocket`, etc.
+Returns the assembled call URL (`${baseUrl}/v1/proxy/${label}${path}`) for
+URL-passing scenarios where you control the request and can attach the
+`X-Public-Key` header yourself.
 
-⚠️ Direct calls do **not** get automatic `X-Public-Key` injection. If your model
-server requires authentication, your model server must validate a token of its
-own (ConnectBase is a dumb pipe, not an auth gate).
+⚠️ **Browser-native APIs that cannot set custom headers will fail with `401`.**
+ConnectBase's proxy requires `X-Public-Key` on every call (header-only — no
+`?api_key=` fallback), so `<img src>`, `new Image()`, native `WebSocket`,
+`<script src>`, EventSource, etc. **cannot authenticate** through this URL.
+Use `cb.endpoint.call()` instead for those cases:
 
 ```typescript
-// Render a ComfyUI output image directly into <img>
-img.src =
-  cb.endpoint.url('comfyui-main', `/view?filename=${encodeURIComponent(name)}`)
+// ✅ Render an image: download via call(), then convert to a blob URL
+const res = await cb.endpoint.call('comfyui-main', {
+  path: `/view?filename=${encodeURIComponent(name)}`,
+})
+img.src = URL.createObjectURL(await res.blob())
+// ...later: URL.revokeObjectURL(img.src)
 ```
 
+For permanent images (works across CDN, survives tunnel restarts), upload the
+blob to `cb.storage` and use `saved.url` — see
+[`examples/ai-image-generator/`](https://github.com/connectbase-world/connectbase/tree/release/examples/ai-image-generator).
+
+When `cb.endpoint.url()` IS the right tool:
+
+- Logging / debugging the resolved tunnel URL
+- Passing the URL to a backend service or worker that will make the call with proper headers
+- Building a `RequestInfo` for a custom `fetch()` wrapper (you control headers)
+
 ```typescript
-// Native WebSocket to a tunneled service
-const ws = new WebSocket(cb.endpoint.url('my-ws-server', '/socket'))
+console.log(cb.endpoint.url('comfyui-main', '/prompt'))
+// → https://api.connectbase.world/v1/proxy/comfyui-main/prompt
+
+// Hand the URL to a Service Worker that injects X-Public-Key
+sw.postMessage({ url: cb.endpoint.url('comfyui-main', '/prompt'), key: PK })
 ```
 
 ### Push Notifications