connectbase-client 3.25.0 → 3.26.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connect Base
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION-v2.md

@@ -0,0 +1,149 @@
+# Migration to v2.0.0 — Presence/Typing 단일화
+
+> 작성일: 2026-04-27
+> 대상 버전: 1.12.x → 2.0.0 (1.13 deprecation 단계 생략, 즉시 제거)
+> 영향: `cb.database.setPresence`, `cb.database.subscribePresence`, `DatabasePresenceState`, WebSocket URL
+
+본 문서는 v1.12.x 이전에서 v2.0.0 으로 업그레이드할 때 필요한 변경 사항을 안내합니다.
+v2.0.0 에서 데이터베이스 측 presence/typing API 가 코드에서 완전히 제거되었습니다
+(호출 시 `TypeError`). presence/typing 의 단일 SoT 는 `cb.realtime.*` 입니다.
+
+## 1. 책임 경계 변경
+
+| 기능 | v1.12.x | v2.0.0 |
+|------|---------|--------|
+| presence 상태 설정/조회/구독 | `cb.database` / `cb.realtime` 양쪽 | `cb.realtime` 만 |
+| typing 상태 | `cb.database` | `cb.realtime` 만 |
+| DB 변경 구독 | `cb.database.connectRealtime` | (변경 없음) |
+| WebSocket URL (DB) | `/v1/realtime/ws` | `/v1/database/realtime/ws` |
+
+## 2. setPresence 마이그레이션
+
+### Before (v1.12.x)
+
+```ts
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+```
+
+### After (v1.13+ / v2)
+
+```ts
+await cb.realtime.setPresence('online', {
+  device: 'web',
+  metadata: { nickname: '홍길동' }
+})
+```
+
+**차이점**
+
+- `cb.realtime.setPresence` 는 `Promise<void>` 를 반환합니다 (기존은 동기 void).
+- `device` 와 `metadata` 가 두 번째 객체 파라미터의 옵션 필드입니다.
+- 상태값에 `'busy'` 가 추가되어 있습니다 (`'online' | 'away' | 'busy' | 'offline'`).
+
+## 3. subscribePresence 마이그레이션
+
+### Before (v1.12.x)
+
+```ts
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen) // string ISO
+})
+```
+
+### After (옵션 1 — 단일 사용자별 구독)
+
+```ts
+const unsub1 = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen) // number (epoch ms)
+})
+const unsub2 = await cb.realtime.subscribePresence('user2', (info) => {
+  console.log(info.userId, info.status, info.eventType) // join/leave/update
+})
+
+// 정리
+unsub1()
+unsub2()
+```
+
+### After (옵션 2 — 앱 전체 변경 일괄 수신)
+
+```ts
+const unsub = cb.realtime.onPresenceChange((info) => {
+  // 모든 사용자의 변경 이벤트가 한 콜백으로 전달됨
+  if (['user1', 'user2'].includes(info.userId)) {
+    console.log(info.userId, info.status)
+  }
+})
+```
+
+**차이점**
+
+| 필드 | v1.12 (`DatabasePresenceState`) | v1.13+ (`PresenceInfo`) |
+|------|-------------------------------|-----------------------|
+| ID | `user_id` (snake) | `userId` (camel) |
+| 마지막 활동 | `last_seen: string` (ISO) | `lastSeen: number` (epoch ms) |
+| 상태 | `'online' \| 'away' \| 'offline'` | `'online' \| 'away' \| 'busy' \| 'offline'` |
+| 이벤트 타입 | (없음) | `eventType?: 'join' \| 'leave' \| 'update'` |
+
+### 변환 헬퍼 (마이그레이션 보조)
+
+기존 `DatabasePresenceState` 모양으로 데이터를 가공하던 코드를 점진적으로 옮길 때 도움이
+되도록, v1 호환 형태(snake_case · ISO 문자열) 로 변환하는 헬퍼 예제. v2.0.0 에서는
+`DatabasePresenceState` type 이 제거되었으므로 inline 타입으로 정의한다.
+
+```ts
+import type { PresenceInfo } from 'connectbase-client'
+
+interface LegacyPresenceState {
+  user_id: string
+  status: 'online' | 'away' | 'offline'
+  last_seen: string
+  device?: string
+  metadata?: Record<string, unknown>
+}
+
+function fromPresenceInfo(info: PresenceInfo): LegacyPresenceState {
+  return {
+    user_id: info.userId,
+    status: info.status === 'busy' ? 'away' : info.status,
+    last_seen: new Date(info.lastSeen).toISOString(),
+    device: info.device,
+    metadata: info.metadata,
+  }
+}
+```
+
+## 4. typing 마이그레이션 (있는 경우)
+
+`cb.database` 에는 공개된 typing 메서드가 없으므로 추가 마이그레이션은 불필요합니다.
+`cb.realtime.startTyping(roomId)` / `cb.realtime.stopTyping(roomId)` /
+`cb.realtime.onTypingChange(roomId, handler)` 를 그대로 사용하세요.
+
+## 5. WebSocket URL 변경
+
+```ts
+await cb.database.connectRealtime({
+  accessToken: 'xxx',
+  dataServerUrl: 'https://data.connectbase.world',
+})
+// SDK 는 자동으로 /v1/database/realtime/ws 로 연결 (v1.13+).
+// 사용자가 dataServerUrl 의 host:port 만 지정하면 path 는 SDK 가 결정.
+```
+
+옛 경로(`/v1/realtime/ws`) 는 v2.0.0 과 함께 서버에서도 제거되었습니다. 사용자 측
+firewall/proxy 에 `/v1/database/realtime/` 경로 허용 규칙이 있는지 확인하세요.
+
+## 6. 런타임 동작 차이
+
+- **v1.12.x**: 두 API 모두 동작.
+- **v2.0.0**: `cb.database.setPresence` / `subscribePresence` 호출 시 `TypeError` (메서드 미존재).
+
+## 7. 자동 마이그레이션 (codemod)
+
+향후 별도 codemod 스크립트가 제공될 예정입니다. 우선은 위 가이드에 따라 수동 변경을
+권장합니다 (필드 네이밍/시그니처 차이가 있어 수동 검토가 안전).
+
+## 8. 문의
+
+- 이슈: GitHub Issues
+- 디스코드: 공식 채널의 `#sdk` 룸