connectbase-client 3.32.0 → 3.33.0

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.33.0] - 2026-06-15
+
+### Added — Realtime WS 자동 SSE fallback (WS 가 차단된 네트워크에서도 AI 스트리밍 동작)
+
+일부 가정용 ISP / 기업 프록시 / 미들박스는 HTTPS 는 통과시키면서 **WebSocket upgrade 만**
+차단한다. 이 경우 `cb.realtime.connect()` 가 영영 `connected` 에 도달하지 못해 reject 되고,
+이어지는 `cb.realtime.stream()` 이 `"Not connected. Call connect() first."` 로 실패했다
+(platform-issue 019eb929 — 특정 end-user 만 WS 연결 실패, 같은 앱/키로 다른 환경은 정상).
+
+- **변경**: `connect()` 가 WS 핸드셰이크에 실패해도 (자격증명이 있으면) reject 하지 않고
+  **SSE degraded 모드로 resolve** 한다. 이후 `stream()` 호출은 자동으로 HTTP SSE
+  (`/v1/public/ai/chat/stream`) 로 흘러 AI 스트리밍이 그대로 동작한다 — **앱 코드 변경 불필요**.
+  Socket.IO/Pusher/Ably 와 동일한 transport graceful-degradation 패턴.
+- **신규 옵션** `RealtimeConnectOptions.fallback?: 'sse' | 'none'` (기본 `'sse'`). `'none'` 이면
+  기존처럼 WS 실패 시 `connect()` 가 reject 한다.
+- **신규 getter** `cb.realtime.transport` (`'ws' | 'sse' | null`) — 현재 활성 transport 확인용.
+- **경계**: SSE 는 단방향이라 fallback 모드에서는 AI `stream()` 만 지원된다. presence/typing/
+  subscribe/sendMessage 등 양방향 기능은 SSE 모드에서 명확한 에러를 던진다. 또한 SSE 스트림은
+  서버가 토큰 카운트를 별도 이벤트로 주지 않으므로 `onDone` 의 `totalTokens`/`promptTokens` 는
+  0 으로 채워진다(`fullText`/`duration` 은 정확). `mcpGroup`(MCP 도구) 은 SSE fallback 미지원.
+- **자격증명 없음**: public key/access token 이 아예 없으면(설정 오류) fallback 기본값이라도
+  `connect()` 는 그대로 reject 한다 — SSE 로도 실패할 요청이므로 실제 버그를 묻지 않는다.
+
+> 이미 배포된 앱도 npm `latest` / CDN UMD 번들 갱신 시 코드 수정 없이 자동 복구됩니다.
+
 ## [3.32.0] - 2026-06-09
 
 ### Fixed — `/v1/public/*` 요청에 무관한 콘솔 쿠키 첨부로 인한 401 / CORS 붕괴