connectbase-client 3.32.0 → 3.34.0

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.34.0] - 2026-06-15
+
+### Changed — `geoQuery` 계약 표준화 (이전엔 백엔드와 형식이 달라 동작하지 않던 기능)
+
+`geoQuery` 의 요청 형식이 백엔드 표준 계약과 달라 실제로는 동작하지 않았다(좌표·연산자
+키 불일치). 단일 표준 계약으로 정렬하여 정상 동작하도록 수정.
+
+- **Breaking (타입)**: `GeoPoint` 가 `{ latitude, longitude }` → **`{ lat, lng }`** 로 변경.
+  서버는 `{ latitude, longitude }` 와 `[lng, lat]` 도 계속 허용하지만 SDK 타입 표준은 `{ lat, lng }`.
+- **Breaking (타입)**: `GeoQuery` 의 `within` → **`box`** 로 변경 (`{ box: { bottom_left, top_right } }`).
+  `near` / `polygon` 은 그대로.
+- 반경 검색은 거리(미터) 가까운 순 정렬, 결과는 `{ results: [{ id, data, distance }], total_count }`.
+- 영역이 지나치게 넓어 후보가 과도하면 결과를 임의로 자르지 않고 명시적 에러를 반환한다.
+
+> 직전까지 `geoQuery` 는 end-to-end 로 동작한 적이 없어 실사용 호환성 파괴는 없습니다.
+
+## [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 붕괴

package/README.md

@@ -644,17 +644,25 @@ const suggestions = await cb.database.autocomplete('table-id', 'sma', 'name', {
 #### Geo Queries
 
 ```typescript
-// Find locations within 5km radius
+// Find locations within 5km radius (query: one of near / box / polygon)
 const nearby = await cb.database.geoQuery('table-id', 'location', {
   near: {
-    center: { latitude: 37.5665, longitude: 126.9780 },
-    max_distance: 5000
+    center: { lat: 37.5665, lng: 126.9780 },
+    max_distance: 5000   // meters
   }
 }, { limit: 20 })
 
 nearby.results.forEach(place => {
   console.log(place.data.name, `${place.distance}m away`)
 })
+
+// Within a rectangle
+await cb.database.geoQuery('table-id', 'location', {
+  box: {
+    bottom_left: { lat: 37.54, lng: 126.96 },
+    top_right: { lat: 37.58, lng: 127.00 }
+  }
+})
 ```
 
 #### Batch & Transactions