connectbase-client 1.10.0 → 1.12.0

package/dist/index.d.mts

@@ -241,7 +241,66 @@ interface AnalyticsRangeOptions {
 interface VisitorListOptions {
     limit?: number;
     offset?: number;
-    sort_by?: 'last_visit' | 'total_visits' | 'total_page_views';
+    /**
+     * 백엔드가 인식하는 정렬 키 — 외 값은 silent 로 default(`last_visit`) 처리됩니다.
+     *
+     * 1.12.0 에서 백엔드 실제 동작에 맞춰 enum 정정 (1.10/1.11 의 `total_visits`/
+     * `total_page_views` 는 백엔드에서 인식되지 않아 항상 default 분기였음).
+     */
+    sort_by?: 'last_visit' | 'visits' | 'page_views' | 'first_visit';
+}
+/**
+ * 멤버별 합산 방문자 그룹 항목.
+ *
+ * 한 명의 회원이 여러 디바이스/브라우저로 접속했을 때 visitor row 들을 합쳐 단일 row.
+ * 익명 visitor 는 `app_member_id == undefined` 로 단일 row 그대로 노출되며 `visitor_count == 1`.
+ *
+ * `visitor_count` 는 "디바이스 수" 가 아닌 **"추적 브라우저 인스턴스 수"** 를 의미합니다.
+ * 같은 디바이스에서 시크릿모드 + 일반모드는 visitor 2 = visitor_count 2 로 카운트됩니다.
+ */
+interface VisitorGroupItem {
+    app_member_id?: string;
+    /** 익명 visitor row 의 경우 단일 visitor_uid. 회원 그룹은 visitor_uids 참조. */
+    visitor_uid?: string;
+    /** 회원 그룹에 속한 visitor_uid 목록. 익명 row 는 undefined. */
+    visitor_uids?: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface VisitorGroupListResponse {
+    groups: VisitorGroupItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface VisitorByMemberResponse {
+    app_member_id: string;
+    visitor_uids: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface MergeVisitorsRequest {
+    source_visitor_uid: string;
+    /** target_visitor_uid 또는 target_member_id 중 하나는 필수. */
+    target_visitor_uid?: string;
+    target_member_id?: string;
+}
+interface MergeVisitorsResponse {
+    success: boolean;
+    target_visitor_id: string;
+    moved_records: number;
+    message?: string;
 }
 declare class SessionManager {
     private _sessionId;
@@ -302,15 +361,38 @@ declare class AnalyticsAPI {
      */
     trackEvent(name: string, properties?: Record<string, unknown>): void;
     /**
-     * 사용자 식별 (로그인 시)
-     * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+     * 사용자 식별 (로그인 직후 호출).
+     *
+     * 이후 모든 방문 배치에 `app_member_id` 가 첨부되어 새 활동은 회원으로 기록됩니다.
+     * 추가로 **현재 visitor_uid 의 기존 익명 활동을 즉시 회원에게 backfill** 하기 위해
+     * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
+     * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
+     *
+     * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
+     *
+     * @example
+     * ```ts
+     * // 로그인 성공 직후
+     * await cb.auth.signIn({ email, password })
+     * cb.analytics.identify(member.id)
+     * ```
      */
     identify(memberId: string): void;
     /**
-     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
-     * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
+     *
+     * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
      */
     setMemberId(memberId: string | null): void;
+    /**
+     * 백엔드 link-member 엔드포인트 한 번 호출 — 즉시 backfill 트리거.
+     *
+     * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
+     *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
+     */
+    private linkMemberSilent;
     /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
     getMemberId(): string | null;
     /**
@@ -363,6 +445,52 @@ declare class AnalyticsAPI {
      * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
      */
     getVisitors(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorListResponse>;
+    /**
+     * 멤버별 합산 방문자 그룹 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * `getVisitors` 와 달리 visitor row 들을 `app_member_id` 로 합쳐 단일 row 로 반환.
+     * 같은 사람이 PC + 모바일 + 태블릿으로 접속한 경우 visitor 3개 → 그룹 1개.
+     * 익명 visitor 는 단일 row 로 그대로 포함되어 페이지네이션이 일관됨.
+     *
+     * @example
+     * ```ts
+     * const { groups } = await cb.analytics.getVisitorGroups('019d8...', { limit: 50 })
+     * for (const g of groups) {
+     *     if (g.app_member_id) console.log(`${g.app_member_id}: ${g.visitor_count} 디바이스`)
+     * }
+     * ```
+     */
+    getVisitorGroups(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorGroupListResponse>;
+    /**
+     * 단건 멤버 합산 방문자 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 어드민 회원 상세 페이지처럼 **한 명만 필요**할 때. 페이지네이션 풀 다운 없이
+     * 한 번의 호출로 합산 결과 반환.
+     *
+     * @example
+     * ```ts
+     * const v = await cb.analytics.getVisitorByMember('019d8...', memberId)
+     * console.log(`${v.visitor_count} 디바이스, 총 ${v.total_page_views} pv`)
+     * ```
+     */
+    getVisitorByMember(storageWebId: string | undefined, memberId: string): Promise<VisitorByMemberResponse>;
+    /**
+     * 두 visitor 를 한 사람으로 통합하는 admin 작업 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 외부 인증 시스템에서 두 visitor 가 동일인임을 알았을 때 사용. source 의 자식 레코드
+     * (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+     * session_recordings) 를 target 으로 옮기고 source visitor 는 삭제됨.
+     *
+     * @param request 둘 중 하나 필수: `target_visitor_uid` 또는 `target_member_id`.
+     * @example
+     * ```ts
+     * await cb.analytics.mergeVisitors('019d8...', {
+     *     source_visitor_uid: 'old-uid',
+     *     target_member_id: '01a...',
+     * })
+     * ```
+     */
+    mergeVisitors(storageWebId: string | undefined, request: MergeVisitorsRequest): Promise<MergeVisitorsResponse>;
     /**
      * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
      * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.

package/dist/index.d.ts

@@ -241,7 +241,66 @@ interface AnalyticsRangeOptions {
 interface VisitorListOptions {
     limit?: number;
     offset?: number;
-    sort_by?: 'last_visit' | 'total_visits' | 'total_page_views';
+    /**
+     * 백엔드가 인식하는 정렬 키 — 외 값은 silent 로 default(`last_visit`) 처리됩니다.
+     *
+     * 1.12.0 에서 백엔드 실제 동작에 맞춰 enum 정정 (1.10/1.11 의 `total_visits`/
+     * `total_page_views` 는 백엔드에서 인식되지 않아 항상 default 분기였음).
+     */
+    sort_by?: 'last_visit' | 'visits' | 'page_views' | 'first_visit';
+}
+/**
+ * 멤버별 합산 방문자 그룹 항목.
+ *
+ * 한 명의 회원이 여러 디바이스/브라우저로 접속했을 때 visitor row 들을 합쳐 단일 row.
+ * 익명 visitor 는 `app_member_id == undefined` 로 단일 row 그대로 노출되며 `visitor_count == 1`.
+ *
+ * `visitor_count` 는 "디바이스 수" 가 아닌 **"추적 브라우저 인스턴스 수"** 를 의미합니다.
+ * 같은 디바이스에서 시크릿모드 + 일반모드는 visitor 2 = visitor_count 2 로 카운트됩니다.
+ */
+interface VisitorGroupItem {
+    app_member_id?: string;
+    /** 익명 visitor row 의 경우 단일 visitor_uid. 회원 그룹은 visitor_uids 참조. */
+    visitor_uid?: string;
+    /** 회원 그룹에 속한 visitor_uid 목록. 익명 row 는 undefined. */
+    visitor_uids?: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface VisitorGroupListResponse {
+    groups: VisitorGroupItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface VisitorByMemberResponse {
+    app_member_id: string;
+    visitor_uids: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface MergeVisitorsRequest {
+    source_visitor_uid: string;
+    /** target_visitor_uid 또는 target_member_id 중 하나는 필수. */
+    target_visitor_uid?: string;
+    target_member_id?: string;
+}
+interface MergeVisitorsResponse {
+    success: boolean;
+    target_visitor_id: string;
+    moved_records: number;
+    message?: string;
 }
 declare class SessionManager {
     private _sessionId;
@@ -302,15 +361,38 @@ declare class AnalyticsAPI {
      */
     trackEvent(name: string, properties?: Record<string, unknown>): void;
     /**
-     * 사용자 식별 (로그인 시)
-     * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+     * 사용자 식별 (로그인 직후 호출).
+     *
+     * 이후 모든 방문 배치에 `app_member_id` 가 첨부되어 새 활동은 회원으로 기록됩니다.
+     * 추가로 **현재 visitor_uid 의 기존 익명 활동을 즉시 회원에게 backfill** 하기 위해
+     * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
+     * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
+     *
+     * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
+     *
+     * @example
+     * ```ts
+     * // 로그인 성공 직후
+     * await cb.auth.signIn({ email, password })
+     * cb.analytics.identify(member.id)
+     * ```
      */
     identify(memberId: string): void;
     /**
-     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
-     * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
+     *
+     * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
      */
     setMemberId(memberId: string | null): void;
+    /**
+     * 백엔드 link-member 엔드포인트 한 번 호출 — 즉시 backfill 트리거.
+     *
+     * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
+     *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
+     */
+    private linkMemberSilent;
     /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
     getMemberId(): string | null;
     /**
@@ -363,6 +445,52 @@ declare class AnalyticsAPI {
      * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
      */
     getVisitors(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorListResponse>;
+    /**
+     * 멤버별 합산 방문자 그룹 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * `getVisitors` 와 달리 visitor row 들을 `app_member_id` 로 합쳐 단일 row 로 반환.
+     * 같은 사람이 PC + 모바일 + 태블릿으로 접속한 경우 visitor 3개 → 그룹 1개.
+     * 익명 visitor 는 단일 row 로 그대로 포함되어 페이지네이션이 일관됨.
+     *
+     * @example
+     * ```ts
+     * const { groups } = await cb.analytics.getVisitorGroups('019d8...', { limit: 50 })
+     * for (const g of groups) {
+     *     if (g.app_member_id) console.log(`${g.app_member_id}: ${g.visitor_count} 디바이스`)
+     * }
+     * ```
+     */
+    getVisitorGroups(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorGroupListResponse>;
+    /**
+     * 단건 멤버 합산 방문자 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 어드민 회원 상세 페이지처럼 **한 명만 필요**할 때. 페이지네이션 풀 다운 없이
+     * 한 번의 호출로 합산 결과 반환.
+     *
+     * @example
+     * ```ts
+     * const v = await cb.analytics.getVisitorByMember('019d8...', memberId)
+     * console.log(`${v.visitor_count} 디바이스, 총 ${v.total_page_views} pv`)
+     * ```
+     */
+    getVisitorByMember(storageWebId: string | undefined, memberId: string): Promise<VisitorByMemberResponse>;
+    /**
+     * 두 visitor 를 한 사람으로 통합하는 admin 작업 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 외부 인증 시스템에서 두 visitor 가 동일인임을 알았을 때 사용. source 의 자식 레코드
+     * (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+     * session_recordings) 를 target 으로 옮기고 source visitor 는 삭제됨.
+     *
+     * @param request 둘 중 하나 필수: `target_visitor_uid` 또는 `target_member_id`.
+     * @example
+     * ```ts
+     * await cb.analytics.mergeVisitors('019d8...', {
+     *     source_visitor_uid: 'old-uid',
+     *     target_member_id: '01a...',
+     * })
+     * ```
+     */
+    mergeVisitors(storageWebId: string | undefined, request: MergeVisitorsRequest): Promise<MergeVisitorsResponse>;
     /**
      * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
      * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.

package/dist/index.js

@@ -8384,15 +8384,31 @@ var AnalyticsAPI = class {
     this.enqueue(event);
   }
   /**
-   * 사용자 식별 (로그인 시)
-   * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+   * 사용자 식별 (로그인 직후 호출).
+   *
+   * 이후 모든 방문 배치에 `app_member_id` 가 첨부되어 새 활동은 회원으로 기록됩니다.
+   * 추가로 **현재 visitor_uid 의 기존 익명 활동을 즉시 회원에게 backfill** 하기 위해
+   * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
+   * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
+   *
+   * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
+   *
+   * @example
+   * ```ts
+   * // 로그인 성공 직후
+   * await cb.auth.signIn({ email, password })
+   * cb.analytics.identify(member.id)
+   * ```
    */
   identify(memberId) {
     this.setMemberId(memberId);
+    this.linkMemberSilent(memberId);
   }
   /**
-   * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
-   * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+   * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
+   *
+   * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
+   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
    */
   setMemberId(memberId) {
     this.memberId = memberId || null;
@@ -8409,6 +8425,25 @@ var AnalyticsAPI = class {
     }
     this.log("Member id set", { memberId });
   }
+  /**
+   * 백엔드 link-member 엔드포인트 한 번 호출 — 즉시 backfill 트리거.
+   *
+   * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
+   *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+   * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
+   */
+  linkMemberSilent(memberId) {
+    if (!this.storageWebId) return;
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    this.http.post(
+      `${prefix}/storages/web/${this.storageWebId}/visitors/link-member`,
+      {
+        visitor_uid: this.session.visitorUid,
+        app_member_id: memberId
+      }
+    ).catch(() => {
+    });
+  }
   /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
   getMemberId() {
     return this.memberId;
@@ -8540,6 +8575,66 @@ var AnalyticsAPI = class {
     const qs = params.toString() ? `?${params.toString()}` : "";
     return this.http.get(`/v1/storages/web/${id}/visitors${qs}`);
   }
+  /**
+   * 멤버별 합산 방문자 그룹 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * `getVisitors` 와 달리 visitor row 들을 `app_member_id` 로 합쳐 단일 row 로 반환.
+   * 같은 사람이 PC + 모바일 + 태블릿으로 접속한 경우 visitor 3개 → 그룹 1개.
+   * 익명 visitor 는 단일 row 로 그대로 포함되어 페이지네이션이 일관됨.
+   *
+   * @example
+   * ```ts
+   * const { groups } = await cb.analytics.getVisitorGroups('019d8...', { limit: 50 })
+   * for (const g of groups) {
+   *     if (g.app_member_id) console.log(`${g.app_member_id}: ${g.visitor_count} 디바이스`)
+   * }
+   * ```
+   */
+  async getVisitorGroups(storageWebId, options) {
+    const id = this.requireServerSideStorageId(storageWebId, "getVisitorGroups");
+    const params = new URLSearchParams();
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.offset !== void 0) params.set("offset", String(options.offset));
+    if (options?.sort_by) params.set("sort_by", options.sort_by);
+    const qs = params.toString() ? `?${params.toString()}` : "";
+    return this.http.get(`/v1/storages/web/${id}/visitor-groups${qs}`);
+  }
+  /**
+   * 단건 멤버 합산 방문자 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * 어드민 회원 상세 페이지처럼 **한 명만 필요**할 때. 페이지네이션 풀 다운 없이
+   * 한 번의 호출로 합산 결과 반환.
+   *
+   * @example
+   * ```ts
+   * const v = await cb.analytics.getVisitorByMember('019d8...', memberId)
+   * console.log(`${v.visitor_count} 디바이스, 총 ${v.total_page_views} pv`)
+   * ```
+   */
+  async getVisitorByMember(storageWebId, memberId) {
+    const id = this.requireServerSideStorageId(storageWebId, "getVisitorByMember");
+    return this.http.get(`/v1/storages/web/${id}/members/${memberId}/visitor`);
+  }
+  /**
+   * 두 visitor 를 한 사람으로 통합하는 admin 작업 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * 외부 인증 시스템에서 두 visitor 가 동일인임을 알았을 때 사용. source 의 자식 레코드
+   * (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+   * session_recordings) 를 target 으로 옮기고 source visitor 는 삭제됨.
+   *
+   * @param request 둘 중 하나 필수: `target_visitor_uid` 또는 `target_member_id`.
+   * @example
+   * ```ts
+   * await cb.analytics.mergeVisitors('019d8...', {
+   *     source_visitor_uid: 'old-uid',
+   *     target_member_id: '01a...',
+   * })
+   * ```
+   */
+  async mergeVisitors(storageWebId, request) {
+    const id = this.requireServerSideStorageId(storageWebId, "mergeVisitors");
+    return this.http.post(`/v1/storages/web/${id}/visitors/merge`, request);
+  }
   /**
    * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
    * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.

package/dist/index.mjs

@@ -8346,15 +8346,31 @@ var AnalyticsAPI = class {
     this.enqueue(event);
   }
   /**
-   * 사용자 식별 (로그인 시)
-   * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+   * 사용자 식별 (로그인 직후 호출).
+   *
+   * 이후 모든 방문 배치에 `app_member_id` 가 첨부되어 새 활동은 회원으로 기록됩니다.
+   * 추가로 **현재 visitor_uid 의 기존 익명 활동을 즉시 회원에게 backfill** 하기 위해
+   * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
+   * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
+   *
+   * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
+   *
+   * @example
+   * ```ts
+   * // 로그인 성공 직후
+   * await cb.auth.signIn({ email, password })
+   * cb.analytics.identify(member.id)
+   * ```
    */
   identify(memberId) {
     this.setMemberId(memberId);
+    this.linkMemberSilent(memberId);
   }
   /**
-   * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
-   * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+   * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
+   *
+   * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
+   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
    */
   setMemberId(memberId) {
     this.memberId = memberId || null;
@@ -8371,6 +8387,25 @@ var AnalyticsAPI = class {
     }
     this.log("Member id set", { memberId });
   }
+  /**
+   * 백엔드 link-member 엔드포인트 한 번 호출 — 즉시 backfill 트리거.
+   *
+   * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
+   *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+   * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
+   */
+  linkMemberSilent(memberId) {
+    if (!this.storageWebId) return;
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    this.http.post(
+      `${prefix}/storages/web/${this.storageWebId}/visitors/link-member`,
+      {
+        visitor_uid: this.session.visitorUid,
+        app_member_id: memberId
+      }
+    ).catch(() => {
+    });
+  }
   /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
   getMemberId() {
     return this.memberId;
@@ -8502,6 +8537,66 @@ var AnalyticsAPI = class {
     const qs = params.toString() ? `?${params.toString()}` : "";
     return this.http.get(`/v1/storages/web/${id}/visitors${qs}`);
   }
+  /**
+   * 멤버별 합산 방문자 그룹 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * `getVisitors` 와 달리 visitor row 들을 `app_member_id` 로 합쳐 단일 row 로 반환.
+   * 같은 사람이 PC + 모바일 + 태블릿으로 접속한 경우 visitor 3개 → 그룹 1개.
+   * 익명 visitor 는 단일 row 로 그대로 포함되어 페이지네이션이 일관됨.
+   *
+   * @example
+   * ```ts
+   * const { groups } = await cb.analytics.getVisitorGroups('019d8...', { limit: 50 })
+   * for (const g of groups) {
+   *     if (g.app_member_id) console.log(`${g.app_member_id}: ${g.visitor_count} 디바이스`)
+   * }
+   * ```
+   */
+  async getVisitorGroups(storageWebId, options) {
+    const id = this.requireServerSideStorageId(storageWebId, "getVisitorGroups");
+    const params = new URLSearchParams();
+    if (options?.limit !== void 0) params.set("limit", String(options.limit));
+    if (options?.offset !== void 0) params.set("offset", String(options.offset));
+    if (options?.sort_by) params.set("sort_by", options.sort_by);
+    const qs = params.toString() ? `?${params.toString()}` : "";
+    return this.http.get(`/v1/storages/web/${id}/visitor-groups${qs}`);
+  }
+  /**
+   * 단건 멤버 합산 방문자 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * 어드민 회원 상세 페이지처럼 **한 명만 필요**할 때. 페이지네이션 풀 다운 없이
+   * 한 번의 호출로 합산 결과 반환.
+   *
+   * @example
+   * ```ts
+   * const v = await cb.analytics.getVisitorByMember('019d8...', memberId)
+   * console.log(`${v.visitor_count} 디바이스, 총 ${v.total_page_views} pv`)
+   * ```
+   */
+  async getVisitorByMember(storageWebId, memberId) {
+    const id = this.requireServerSideStorageId(storageWebId, "getVisitorByMember");
+    return this.http.get(`/v1/storages/web/${id}/members/${memberId}/visitor`);
+  }
+  /**
+   * 두 visitor 를 한 사람으로 통합하는 admin 작업 — JWT/cb_sk_ 인증 필요. (1.11+)
+   *
+   * 외부 인증 시스템에서 두 visitor 가 동일인임을 알았을 때 사용. source 의 자식 레코드
+   * (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+   * session_recordings) 를 target 으로 옮기고 source visitor 는 삭제됨.
+   *
+   * @param request 둘 중 하나 필수: `target_visitor_uid` 또는 `target_member_id`.
+   * @example
+   * ```ts
+   * await cb.analytics.mergeVisitors('019d8...', {
+   *     source_visitor_uid: 'old-uid',
+   *     target_member_id: '01a...',
+   * })
+   * ```
+   */
+  async mergeVisitors(storageWebId, request) {
+    const id = this.requireServerSideStorageId(storageWebId, "mergeVisitors");
+    return this.http.post(`/v1/storages/web/${id}/visitors/merge`, request);
+  }
   /**
    * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
    * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",