connectbase-client 1.10.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,168 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [2.0.0] - 2026-04-27 — BREAKING
+
+Realtime presence/typing 단일화의 최종 단계. 1.13 deprecation 단계를 건너뛰고 즉시
+deprecated 코드를 제거. presence/typing 의 단일 SoT 는 `cb.realtime.*`.
+
+### Removed (BREAKING)
+
+- **`cb.database.setPresence(status, device, metadata)`** — 코드 자체 제거. 호출 시 `TypeError`.
+- **`cb.database.subscribePresence(userIds, callback)`** — 코드 자체 제거.
+- **`DatabasePresenceState`** type — `PresenceInfo` (from `'./realtime'`) 사용.
+- 1.13 에서 추가됐던 deprecation `console.warn` 헬퍼도 함께 제거 (필요 없음).
+
+### Migration
+
+```ts
+// Before
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen)
+})
+
+// After
+await cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+const unsub = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen)
+})
+```
+
+자세한 가이드: [MIGRATION-v2.md](./MIGRATION-v2.md). 필드 차이는 `user_id`→`userId`,
+`last_seen` (ISO) → `lastSeen` (epoch ms), `'busy'` 상태 추가.
+
+### Server-side
+
+데이터 서버 측 presence/typing 코드도 함께 제거되었습니다. `presence_set` / `presence_subscribe`
+/ `typing_*` 메시지를 데이터 서버 WebSocket 으로 보내면 `USE_SOCKET_SERVER` 에러가 반환됩니다.
+
+## [1.13.0] - 2026-04-27
+
+Realtime presence/typing 단일화 — `cb.database.setPresence` / `cb.database.subscribePresence`
+는 v2.0.0 에서 제거됩니다. 신규 코드는 `cb.realtime.*` 를 사용하세요. 자세한 마이그레이션은
+[MIGRATION-v2.md](./MIGRATION-v2.md) 참고.
+
+### Deprecated
+
+- **`cb.database.setPresence(status, device, metadata)`** → `cb.realtime.setPresence(status, { device, metadata })`
+- **`cb.database.subscribePresence(userIds, onPresence)`** → `cb.realtime.subscribePresence(userId, handler)` 또는
+  `cb.realtime.onPresenceChange(handler)` (다중 사용자 일괄 수신).
+- **`DatabasePresenceState`** type → `PresenceInfo` (from `'./realtime'`).
+  - 필드 네이밍: `user_id` → `userId`, `last_seen` (ISO) → `lastSeen` (epoch ms 숫자).
+  - 상태값: `'busy'` 추가 (PresenceInfo 만 지원).
+
+호출 시 개발 환경(`process.env.NODE_ENV !== 'production'`)에서 `console.warn` 이 1회 출력됩니다.
+런타임 동작은 1.12.x 와 동일합니다 (이번 버전은 deprecate 만, 코드 제거는 v2.0.0).
+
+### Changed
+
+- **WebSocket URL 기본값** `cb.database.connectRealtime` 의 기본 endpoint 가
+  `/v1/realtime/ws` → `/v1/database/realtime/ws` 로 변경. 기존 경로는 30일간 alias 로
+  유지되며 응답에 `Sunset` (RFC 8594) + `X-Deprecated-Endpoint` 헤더가 부착됩니다.
+  명시적으로 `dataServerUrl` 을 지정한 경우 자동 변환은 하지 않습니다 (Hyrum's Law 준수).
+
+### Migration
+
+```ts
+// Before (1.12.x)
+cb.database.setPresence('online', 'web', { nickname: '홍길동' })
+cb.database.subscribePresence(['user1', 'user2'], (states) => {
+  console.log(states['user1']?.last_seen) // ISO string
+})
+
+// After (1.13+, 권장 — v2 호환)
+cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+const unsubscribe = await cb.realtime.subscribePresence('user1', (info) => {
+  console.log(info.lastSeen) // epoch ms number
+})
+```
+
+## [1.12.0] - 2026-04-26
+
+Analytics 조회 정렬 옵션 정합성 수정 — `VisitorListOptions.sort_by` 의 TypeScript
+union 을 백엔드가 실제로 인식하는 값으로 정정합니다. 1.10/1.11 의 SDK 타입은
+`'last_visit' | 'total_visits' | 'total_page_views'` 였으나 백엔드 정렬 분기
+(`web_visitor_repository.GetStorageVisitors`,
+`web_visitor_service.GetVisitorGroupsByMember`) 는 `last_visit` 외 값을
+인식하지 못해 항상 default(`last_visit`) 분기로 떨어졌습니다 — silent 잘못된 정렬.
+
+### Changed — `VisitorListOptions.sort_by` 타입
+
+- 변경 전 (1.10/1.11): `'last_visit' | 'total_visits' | 'total_page_views'`
+- 변경 후 (1.12+): `'last_visit' | 'visits' | 'page_views' | 'first_visit'`
+- 영향 메서드: `cb.analytics.getVisitors()`, `cb.analytics.getVisitorGroups()`.
+- 런타임은 SDK 가 sort_by 문자열을 그대로 백엔드에 전달하므로, 새 값을 쓰면
+  비로소 의도한 정렬이 동작합니다. 1.10/1.11 코드에서 `total_visits` /
+  `total_page_views` 를 넘긴 호출은 실제로는 default `last_visit` 정렬 결과를
+  받고 있었던 점에 주의.
+
+### Migration
+
+```ts
+// Before (1.10/1.11): 컴파일은 통과하지만 런타임은 last_visit 정렬
+cb.analytics.getVisitors('019d8...', { sort_by: 'total_visits' })
+
+// After (1.12+): 의도한대로 visits 기준 정렬
+cb.analytics.getVisitors('019d8...', { sort_by: 'visits' })
+cb.analytics.getVisitors('019d8...', { sort_by: 'page_views' })   // 페이지뷰 누적 기준
+cb.analytics.getVisitors('019d8...', { sort_by: 'first_visit' })  // 최초 방문일 기준
+```
+
+기존 코드가 `'last_visit'` 만 사용했다면 변경 불필요 (대부분의 호출).
+타입 변경은 breaking 이지만 런타임 호환은 유지됩니다 — 이전 union 의 두 값은
+원래 동작하지 않았기 때문.
+
+## [1.11.0] - 2026-04-26
+
+Analytics 사용자 통합 강화 — 멤버별 합산 방문자 조회, 단건 멤버 조회, 즉시 backfill,
+Visitor merge admin API. sisun 팀의 1.10 이후 후속 피드백이 시작점이며, 어드민에서
+"회원 단위 합산 방문자" 위젯을 위한 페이지네이션 풀 다운 우회 코드를 SDK 한 줄 호출로
+대체할 수 있도록 했습니다. 모든 추가 메서드는 `cb.analytics` 네임스페이스에 들어가며
+JWT/cb_sk_ dual-auth 로 호출할 수 있습니다.
+
+### Added — `cb.analytics.getVisitorGroups(storageWebId?, options?)`
+
+- 같은 `app_member_id` 의 visitor row 들을 서버 단에서 합산해 단일 row 로 반환.
+  익명 visitor 는 단일 row 로 그대로 노출되어 페이지네이션 의미가 일관됨.
+- 응답 필드: `app_member_id`, `visitor_uids[]`, `visitor_count`, `total_visits`,
+  `total_page_views`, `first_visit_at`(MIN), `last_visit_at`(MAX), `country`, `is_bot`.
+- `visitor_count` 는 **"디바이스 수" 가 아닌 "추적 브라우저 인스턴스 수"** 입니다 (시크릿/일반
+  모드는 별도 카운트).
+- 백엔드 `GET /v1/storages/web/:id/visitor-groups` 신설 (dual-auth).
+
+### Added — `cb.analytics.getVisitorByMember(storageWebId?, memberId)`
+
+- 어드민 회원 상세 페이지처럼 한 명만 필요할 때. 페이지네이션 풀 다운 없이 한 번 호출.
+- 응답은 위 group item 과 동일 형태 (단건).
+- 백엔드 `GET /v1/storages/web/:id/members/:member_id/visitor` 신설.
+
+### Added — `cb.analytics.mergeVisitors(storageWebId?, request)`
+
+- 두 visitor 가 동일인임을 외부에서 알게 됐을 때 admin 작업으로 통합. source 의 자식
+  레코드 (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+  session_recordings) 를 target 으로 옮긴 뒤 source 삭제. 단일 트랜잭션, 부분 실패 시
+  전체 롤백.
+- 입력: `source_visitor_uid` 필수 + (`target_visitor_uid` 또는 `target_member_id`) 중
+  하나 필수. `target_member_id` 만 주면 그 멤버의 가장 최근 활동 visitor 를 target 으로 잡음.
+- 응답: `target_visitor_id`, `moved_records`(이전된 자식 레코드 수).
+- 제약: `first_visit_at` 은 ent Immutable 필드라 target 값을 바꾸지 않습니다 (daily 가
+  실제 이력 보존). source/target 은 같은 storage_web 에 속해야 합니다.
+- 백엔드 `POST /v1/storages/web/:id/visitors/merge` 신설.
+
+### Changed — `cb.analytics.identify(memberId)` 동작 보강
+
+- 1.10 까지: `identify()` 호출 후 다음 batch 가 백엔드에 닿을 때 게스트 visitor 가 회원으로
+  자동 연결됨 (백엔드 BatchRecordVisit 의 자동 LinkMember 로직).
+- 1.11+: `identify()` 가 즉시 `POST /visitors/link-member` 를 한 번 호출하여 backfill 을
+  당겨옵니다. 첫 페이지뷰 전 호출 시 404 발생 가능 — silent fail (다음 batch 가 자가 복구).
+- `setMemberId(memberId)` 는 즉시 backfill 을 호출하지 않습니다 (이전과 동일 동작).
+
+### Migration
+
+기존 호출은 그대로 동작합니다. `identify()` 의 즉시 backfill 동작이 추가 HTTP 요청 1번을
+유발하므로, 같은 효과를 다음 batch 까지 미루고 싶다면 `setMemberId()` 를 사용하세요.
+
 ## [1.10.0] - 2026-04-26
 
 OAuth 콜백 응답 email 노출 + Analytics 조회 메서드 신규 + Functions 자동화용 Push 발송 메서드 신규.

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` 룸

package/README.md

@@ -708,6 +708,29 @@ await subscription.unsubscribe()
 await cb.realtime.disconnect()
 ```
 
+#### Presence / Typing
+
+Presence(온라인 상태) 와 typing(입력 중 표시) 은 `cb.realtime.*` 가 단일 SoT 입니다.
+v2.0.0 에서 `cb.database.setPresence` / `subscribePresence` 는 제거되었습니다.
+v1.x 에서 마이그레이션은 [MIGRATION-v2.md](./MIGRATION-v2.md) 참고.
+
+```typescript
+// 본인 온라인 상태 publish
+await cb.realtime.setPresence('online', { device: 'web', metadata: { nickname: '홍길동' } })
+
+// 다른 사용자 상태 구독
+const unsub = await cb.realtime.subscribePresence('user-id', (info) => {
+  console.log(info.userId, info.status, info.eventType) // join | leave | update
+})
+
+// 룸 단위 typing indicator
+await cb.realtime.startTyping('room-id')
+await cb.realtime.stopTyping('room-id')
+const unsubTyping = await cb.realtime.onTypingChange('room-id', (typing) => {
+  console.log(typing.users) // 현재 입력 중인 사용자 ID 목록
+})
+```
+
 #### AI Streaming
 
 Real-time AI text generation using Gemini API through WebSocket.