connectbase-client 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -3,6 +3,91 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [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 발송 메서드 신규.