connectbase-client 6.4.0 → 6.5.0

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [6.5.0] - 2026-10-21
+
+### Added — 실시간 연결 거부 사유: `RealtimeConnectionError`
+
+서버가 실시간 연결을 받지 않으면 `cb.realtime.connect()` 가 이유를 담은 `RealtimeConnectionError` 를 던집니다.
+`code`(`connection_limit_exceeded`, `quota_exceeded`, `server_at_capacity`, `auth_unavailable`, `unauthorized`,
+`forbidden`, `invalid_user_id`, `internal_error`), `retryable`, `closeCode`(4000 + HTTP 상태), `details`
+(예: 동시접속 초과의 `current`/`limit`)가 들어 있습니다.
+
+브라우저의 WebSocket API 는 실패한 핸드셰이크의 HTTP 상태를 읽지 못해, 지금까지는 동시접속 초과도 인증 실패도
+"Connection timeout"/"Failed to connect" 로만 보였습니다. SDK 가 `reject_mode=close` 로 협상하면 서버가 연결을
+받은 뒤 이유를 보내고 4xxx 로 닫습니다(서버가 구버전이면 예전과 같게 동작합니다).
+
+```ts
+try {
+  await cb.realtime.connect()
+} catch (e) {
+  if (e instanceof RealtimeConnectionError && e.code === 'connection_limit_exceeded') {
+    showFull(e.details?.limit)
+  }
+}
+```
+
+### Changed — 서버가 거부한 연결은 SSE 폴백으로 넘어가지 않습니다
+
+예전에는 거부도 네트워크 실패처럼 처리돼 SSE degraded 모드로 넘어갔고, `connect()` 는 성공했는데 `subscribe`/
+`send` 가 나중에 이유 없이 실패했습니다. 이제 거부는 위 에러로 던집니다. 네트워크/프록시가 WebSocket 을 막는
+경우(사유 없는 실패)는 종전처럼 SSE 로 넘어갑니다.
+
+자동 재연결 중에 거부되면 `retryable` 이면 지수 백오프로 계속 시도하고, 아니면(`unauthorized`, `quota_exceeded`
+등) 재연결을 멈추고 `onError` 로 같은 에러를 보냅니다.
+
+### Changed — 첫 연결 전에 저지연 원본을 묻습니다
+
+realtime 만 쓰는 페이지는 WS 를 열기 전에 REST 를 부르지 않아 direct 원본(`ws-direct`)을 배우지 못했고,
+첫 연결이 늘 Cloudflare 를 거쳐 한국 사용자는 미국(LAX)을 도는 ~270ms 로 붙었습니다. 이제 direct 원본을 아직
+모르면 `connect()` 가 `GET /v1/public/edge-hints` 를 한 번(최대 1.5초) 묻고 연결합니다. 해외 사용자와 킬 스위치가
+켜진 경우엔 빈 응답이라 원래 소켓 주소로 갑니다. 세션당 한 번만 묻습니다.
+
+### Fixed — 재연결 시도가 한 번이라도 실패하면 구독이 복구되지 않던 문제
+
+연결이 끊긴 뒤 첫 재연결 시도가 실패하면(서버 롤링 재시작 등) 다음 시도에서 연결에 성공해도 카테고리 구독,
+프레전스 구독, 타이핑 핸들러가 하나도 복구되지 않았습니다. 실패한 시도마다 이미 비워진 구독 맵으로 복구
+스냅샷을 덮었기 때문입니다. 이제 끊긴 순간의 스냅샷을 재연결에 성공할 때까지 유지합니다.
+
+### Fixed — 재연결 대기 중 `disconnect()` 해도 다시 연결되던 문제
+
+백오프 대기 중에 `disconnect()` 를 부르면 예약된 재연결이 그대로 실행돼 다시 연결됐습니다. 이제 대기가 끝났을 때
+상태가 재연결 중이 아니면 연결하지 않습니다.
+
 ## [6.4.0] - 2026-10-01
 
 ### Added — 웹 배포에 브라우저 ML 모델 확장자 허용 (`.onnx` `.tflite` `.task` `.safetensors`)

package/README.md

@@ -1006,6 +1006,29 @@ cb.realtime.transport        // 'ws' | 'sse' | null
 > **v5 → v6 BREAKING**: v5 까지 `isConnected()` 는 SSE 폴백에서도 true 였습니다.
 > 스트리밍 게이팅에 쓰고 있었다면 `isStreamReady()` 로 바꾸세요.
 
+#### Connection rejected (v6.5.0)
+
+서버가 연결을 받지 않으면(동시접속 한도, 할당량, 인증 실패 등) `connect()` 가 `RealtimeConnectionError` 를
+던집니다. 이 경우는 SSE 폴백으로 넘어가지 않습니다 — 네트워크는 정상이고 서버가 거부한 것이기 때문입니다.
+
+```typescript
+import { RealtimeConnectionError } from 'connectbase-client'
+
+try {
+  await cb.realtime.connect()
+} catch (e) {
+  if (e instanceof RealtimeConnectionError) {
+    e.code       // 'connection_limit_exceeded' | 'quota_exceeded' | 'server_at_capacity' | 'unauthorized' | ...
+    e.retryable  // 나중에 다시 연결하면 성공할 수 있는지
+    e.details    // 예: { current: 100, limit: 100 }
+  }
+}
+```
+
+자동 재연결 중의 거부는 `retryable` 이면 백오프로 계속 시도하고, 아니면 재연결을 멈추고 `onError` 로 같은 에러를
+보냅니다. 서버 코드(함수)에서 realtime 을 쓴다면 끝날 때 `cb.realtime.disconnect()` 를 부르세요 — 함수 컨테이너는
+호출 사이에 재사용되므로 닫지 않은 소켓이 호출마다 쌓입니다(`unsubscribe()` 는 소켓을 닫지 않습니다).
+
 #### Presence / Typing
 
 Presence(온라인 상태) 와 typing(입력 중 표시) 은 `cb.realtime.*` 가 단일 SoT 입니다.

package/dist/cli.js

@@ -156,7 +156,7 @@ function handleTunnelError(msg, appId, localPort) {
 }
 
 // src/cli.ts
-var VERSION = "6.4.0" ? "6.4.0" : getPackageVersion();
+var VERSION = "6.5.0" ? "6.5.0" : getPackageVersion();
 var DEFAULT_BASE_URL = "https://api.connectbase.world";
 var colors = {
   reset: "\x1B[0m",