connectbase-client 1.9.1 → 1.12.0

package/CHANGELOG.md

@@ -3,6 +3,141 @@
 본 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 발송 메서드 신규.
+sisun 팀(`019d85c7-...`) 의 운영 피드백 3건이 시작점이며, 백엔드 라우트는 콘솔 JWT 와 User Secret Key(`cb_sk_`)
+둘 다 받는 dual-auth 로 확장되었습니다. 모든 변경은 추가 성격이며 기존 호출 시그니처는 유지됩니다.
+
+### Added — OAuth 콜백 응답에 `email`
+
+- `OAuthCallbackResponse.email?: string` — `signInWithPopup` / `getCallbackResult` /
+  `exchangeCodeFromCallback` 모두 첫 응답에 이메일을 포함하도록 확장.
+- 백엔드는 2026-04-19 부터 OAuth 신규 가입/재로그인 시 `AppMember.email` 을 자동 저장해왔으나,
+  콜백 응답 DTO 에는 노출되지 않아 SDK 사용자가 추가로 `getMember()` 를 호출해야 했음. 이번
+  릴리즈로 한 번의 로그인 응답만으로 이메일을 확보할 수 있다.
+- Apple private relay / 이메일 권한 미동의 시 `email` 은 비어 있을 수 있다 (선택 필드).
+
+### Added — Analytics 조회 메서드 (Functions / cb_sk_ 전용)
+
+- `cb.analytics.getPopularPages(storageWebId?, options?)` — 인기 페이지.
+- `cb.analytics.getNavigationFlow(storageWebId?, options?)` — 페이지 전환 플로우 (Sankey).
+- `cb.analytics.getVisitors(storageWebId?, options?)` — 방문자 목록.
+- 백엔드 라우트 `/v1/storages/web/:id/{popular-pages,navigation/flow,visitors}` 가 dual-auth 로 변경되어
+  콘솔 JWT 외에 User Secret Key(`cb_sk_`) 호출도 허용. 어드민 앱이 Function 에서 호출해 자체
+  대시보드를 구성할 수 있다.
+- 브라우저 SDK (Public Key `cb_pk_`) 인스턴스에서는 호출 시 명확한 에러를 던져 권한 누설을 차단.
+
+### Added — Push 발송 메서드 `cb.push.sendToMembers`
+
+- `cb.push.sendToMembers(appId, memberIds, payload)` — Functions / 서버 자동화 환경에서
+  회원 ID 목록으로 푸시 발송. payload 는 title/body/imageUrl/data/platforms/ttlSeconds/priority/
+  clickAction/scheduledAt 지원.
+- 백엔드 `/v1/apps/:appID/push/send` 가 cb_sk_ 인증을 받도록 dual-auth 로 변경. 1.9 까지 안내되던
+  `CONSOLE_ACCESS_TOKEN` (만료 있는 콘솔 JWT) 우회 패턴이 더 이상 필요 없음.
+- Public Key 인스턴스 호출 시 명확한 에러로 차단.
+
+### Changed — 문서
+
+- `embedded/sections/15-sdk-push.md` — Functions 발송 예제를 cb_sk_ 권장 패턴으로 갱신, legacy
+  `CONSOLE_ACCESS_TOKEN` 마이그레이션 안내 추가.
+- `embedded/sections/33-sdk-analytics.md`, `38-sdk-analytics-advanced.md` — REST 표에
+  visitors/popular-pages/navigation/flow 라우트의 dual-auth 를 명시.
+
+### Migration
+
+기존 호출은 그대로 동작합니다.
+
+- OAuth: `signInWithPopup()` 결과의 `email` 이 신규 추가 — 사용 안 해도 무방.
+- Analytics 조회: 1.9 까지 SDK 에 조회 메서드가 없었으므로 신규 도입.
+- Push 발송: Functions 코드의 `fetch + Authorization: Bearer ${CONSOLE_ACCESS_TOKEN}` 패턴은
+  유지 가능하지만, secret 을 `cb_sk_` 로 교체 후 SDK 메서드로 옮기는 것을 권장 (만료 없음).
+
 ## [1.9.1] - 2026-04-25
 
 문서 정합성 패치. 런타임 동작은 1.9.0 과 동일합니다.