connectbase-client 3.31.0 → 3.33.0

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 본 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 붕괴
+
+`*.web.connectbase.world` 같은 ConnectBase 서브도메인에 배포된 앱에서, **ConnectBase 콘솔에
+로그인된 브라우저**로 그 사이트를 보면 public API 호출(AI 챗 스트림, 함수 invoke, 테이블 조회,
+에러 트래커 배치)이 전부 401 로 실패하던 회귀를 차단한다 (platform-issue 019ea60d).
+
+- **근본 원인**: SDK 의 모든 fetch 가 `credentials:'include'` 로 나갔다. 앱이 ConnectBase
+  서브도메인에 있으면 브라우저가 부모 도메인 `.connectbase.world` 의 **무관한 콘솔 세션 쿠키**까지
+  자동 첨부한다. publicKey(`X-Public-Key`)로 인증하는 `/v1/public/*` 엔드포인트에 그 콘솔 User
+  JWT 쿠키가 붙으면 401 이 나고, credentialed 요청에 `Access-Control-Allow-Origin: *` 가 충돌해
+  브라우저가 응답 읽기까지 CORS 로 차단됐다. `autoRestoreSession:false` 로도 회피 불가(쿠키 첨부는
+  브라우저 동작이라 앱 코드로 못 막음).
+- **변경**: `/v1/public/*` 요청은 `credentials:'omit'` 으로 보내 쿠키 자체를 첨부하지 않는다.
+  이 엔드포인트들은 헤더로만 인증하므로 쿠키가 불필요하다. 멤버 세션을 발급/회전하는
+  `/v1/auth/*`(re-issue 등)는 HttpOnly refresh cookie 가 필요하므로 `'include'` 를 유지한다.
+
+> 이미 배포된 앱도 npm `latest` / CDN UMD 번들 갱신 시 코드 수정 없이 복구됩니다.
+
+### Added — `AIChatRequest.toolResultMaxChars` / `mcpPublicKey` 노출
+
+게이트웨이는 지원하지만 SDK 타입에 빠져 있던 두 `chat`/`chatStream` 파라미터를 노출한다.
+
+- **`toolResultMaxChars?: number`**: 서버측 도구 그룹 실행(`toolGroupId`)에서 각 도구 결과를 모델에
+  **재투입하기 전** N 자(rune)로 잘라낸다(표시값 `tool_end.result` 는 원문 유지). 거대한 도구
+  결과(예: `browser_snapshot`)가 컨텍스트를 부풀려 prefill 지연을 유발할 때 압축용
+  (platform-issue 019ea60f, 게이트웨이는 019e8b80 에서 이미 출시됨).
+- **`mcpPublicKey?: string`**: 요청에 포함한 MCP 도구를 호출할 외부 MCP 서버의 Public Key.
+
 ## [3.31.0] - 2026-06-05
 
 ### Added — OAuth 리다이렉트 콜백 **부팅 자동 소비** 안전망