connectbase-client 5.13.0 → 6.0.0

package/CHANGELOG.md

@@ -3,6 +3,75 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [6.0.0] - 2026-08-20
+
+### BREAKING — `realtime.isConnected()` 가 SSE 폴백에서 더 이상 true 를 반환하지 않습니다
+
+WS 가 차단된 망에서 SDK 는 SSE 폴백으로 내려가는데, 이 모드에서는 `subscribe` / `sendMessage` /
+`setPresence` / typing 이 **전부 예외를 던집니다**. 그런데 `isConnected()` 는 계속 true 였습니다.
+앱은 "연결됨"으로 판단하고 진행하지만 아무것도 오가지 않아, 다른 사용자가 화면에서 사라지고
+채팅이 나가지 않는데 에러도 없는 상태로 조용히 멈췄습니다 (platform-issue `01a01e6a-3cb1`).
+
+이제 `isConnected()` 는 **pub/sub 사용 가능 여부**를 반영합니다 — WS 로 연결됐을 때만 true 입니다.
+
+마이그레이션:
+
+| 하려던 일 | 이전 | 지금 |
+|---|---|---|
+| pub/sub 가능한지 | `isConnected()` | `isConnected()` (그대로) |
+| AI 스트리밍 가능한지 | `isConnected()` | **`isStreamReady()`** |
+| 다운그레이드 안내 | `transport !== 'ws'` 폴링 | **`isDegraded()`** |
+
+`stream()` 게이팅에 `isConnected()` 를 쓰고 있었다면 `isStreamReady()` 로 바꾸세요. 그대로 두면
+SSE 폴백 상태에서 스트리밍을 건너뛰게 됩니다.
+
+### Added — `realtime.isDegraded()` / `realtime.isStreamReady()`
+
+- `isDegraded()`: SSE 폴백으로 내려간 상태. 사용자에게 "제한된 네트워크" 배너를 띄울 지점입니다.
+- `isStreamReady()`: WS/SSE 무관하게 연결이 서 있는지. 종전 `isConnected()` 와 같은 판정입니다.
+
+### Added — `webrtc.createSession()`: 기능별 독립 WebRTC 세션
+
+`cb.webrtc` 는 인스턴스 하나가 소켓 하나와 룸 하나만 들고 이벤트 핸들러도 전역이라, 한 앱에
+WebRTC 기능이 둘 이상이면(예: 공간 음성채팅 + 1:1 통화) 서로 연결을 뺏고 이벤트가 교차했습니다
+— 음성채팅이 연결을 선점하면 전화가 "이미 연결되어 있거나 연결 중입니다"로 100% 실패하고,
+음성채팅에 누가 들어오면 전화 훅의 `onRemoteStream` 이 발동해 통화 화면이 뜨는 식입니다
+(platform-issue `01a01e6a-38cc`).
+
+```typescript
+const voice = cb.webrtc.createSession()
+const call  = cb.webrtc.createSession()
+
+voice.onRemoteStream((peerId, stream) => attachToSpatialAudio(peerId, stream))
+call.onRemoteStream((peerId, stream) => showCallScreen(stream))
+
+await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+```
+
+각 세션은 소켓, 룸, 리스너, 피어 연결을 독립적으로 갖고 인증 정보만 공유합니다.
+
+### Added — `webrtc.switchRoom(roomId, options?)`
+
+`disconnect()` 후 곧바로 `connect()` 하던 룸 전환을 안전하게 감쌉니다. 생략한 옵션
+(`userId` / `isBroadcaster` / `localStream`)은 현재 세션 값을 이어받습니다.
+
+### Fixed — `webrtc.disconnect()` 후 옛 소켓의 늦은 `onclose` 가 새 연결을 오염시키던 문제
+
+`disconnect()` 가 `this.ws = null` 로 참조만 끊고 핸들러를 떼지 않아, 뒤늦게 도착한 close
+이벤트가 **이미 새로 연결 중인 인스턴스**에 대고 실행됐습니다. `handleDisconnect()` 가 state 를
+'disconnected' 로 덮어쓰고 새로 만든 피어 연결까지 정리해, 룸 A → 룸 B 전환이 "끊겼다"로
+오판됐습니다 (platform-issue `01a01e6a-3550`).
+
+소켓마다 세대(generation) 토큰을 발급해 핸들러가 자기 소켓의 이벤트인지 확인하고,
+`disconnect()` 는 핸들러를 명시적으로 떼어냅니다. 연결 중인 소켓도 확실히 닫아 서버에 유령
+피어로 남지 않게 했습니다.
+
+### Added — `ICEServersResponse.expires_at`
+
+ephemeral TURN 자격증명의 만료 시각(Unix 초). STUN 전용 구성에서는 0 입니다. 서버는 이미
+내려주고 있었는데 타입에 없었습니다.
+
 ## [5.13.0] - 2026-08-13
 
 ### Added — 패키징 앱 네이티브 브릿지: OAuth 인앱 브라우저 로그인 + 데스크톱 창 제어/CPU/클립보드 `has` 노출

package/README.md

@@ -939,6 +939,22 @@ await subscription.unsubscribe()
 await cb.realtime.disconnect()
 ```
 
+#### Connection state (v6.0.0)
+
+WS 가 차단된 망에서 SDK 는 SSE 폴백으로 내려갑니다. 이 모드에서는 AI 스트리밍만 되고
+pub/sub 계열(`subscribe` / `sendMessage` / `setPresence` / typing)은 예외를 던집니다.
+그래서 판정이 세 갈래입니다:
+
+```typescript
+cb.realtime.isConnected()    // pub/sub 가능? — WS 로 연결됐을 때만 true
+cb.realtime.isStreamReady()  // AI 스트리밍 가능? — WS/SSE 무관, 연결만 서 있으면 true
+cb.realtime.isDegraded()     // SSE 폴백으로 내려갔나? — 사용자 안내용
+cb.realtime.transport        // 'ws' | 'sse' | null
+```
+
+> **v5 → v6 BREAKING**: v5 까지 `isConnected()` 는 SSE 폴백에서도 true 였습니다.
+> 스트리밍 게이팅에 쓰고 있었다면 `isStreamReady()` 로 바꾸세요.
+
 #### Presence / Typing
 
 Presence(온라인 상태) 와 typing(입력 중 표시) 은 `cb.realtime.*` 가 단일 SoT 입니다.
@@ -1286,10 +1302,32 @@ cb.webrtc.onRemoteStream((peerId, remoteStream) => {
   videoElement.srcObject = remoteStream
 })
 
+// 룸 전환 (생략한 옵션은 현재 세션 값을 이어받습니다)
+await cb.webrtc.switchRoom('live:room-2')
+
 // 연결 해제
 cb.webrtc.disconnect()
 ```
 
+#### 기능별 독립 세션 (v6.0.0)
+
+`cb.webrtc` 는 소켓 하나와 룸 하나만 듭니다. 한 앱에 WebRTC 기능이 둘 이상이면
+(예: 공간 음성채팅 + 1:1 통화) 기능마다 세션을 하나씩 만드세요 — 각자 소켓, 룸,
+이벤트 리스너, 피어 연결을 독립적으로 갖습니다.
+
+```typescript
+const voice = cb.webrtc.createSession()
+const call  = cb.webrtc.createSession()
+
+voice.onRemoteStream((peerId, s) => attachToSpatialAudio(peerId, s))
+call.onRemoteStream((peerId, s) => showCallScreen(s))
+
+await voice.connect({ roomId: 'voice:lobby', localStream: mic })
+await call.connect({ roomId: 'call:alice-bob', localStream: mic })
+
+call.disconnect()   // voice 는 그대로 유지됩니다
+```
+
 ### Payments & Subscriptions
 
 ```typescript