connectbase-client 1.9.1 → 1.12.0

package/dist/index.mjs

@@ -4436,11 +4436,13 @@ var OAuthAPI = class {
           reject(new Error(event.data.error));
           return;
         }
+        const rawEmail = event.data.email;
         const result = {
           member_id: event.data.member_id,
           access_token: event.data.access_token,
           refresh_token: event.data.refresh_token,
-          is_new_member: event.data.is_new_member === "true" || event.data.is_new_member === true
+          is_new_member: event.data.is_new_member === "true" || event.data.is_new_member === true,
+          ...typeof rawEmail === "string" && rawEmail.length > 0 ? { email: rawEmail } : {}
         };
         this.http.setTokens(result.access_token, result.refresh_token);
         resolve(result);
@@ -4508,11 +4510,13 @@ var OAuthAPI = class {
     if (!accessToken || !refreshToken || !memberId) {
       return null;
     }
+    const emailParam = params.get("email");
     const result = {
       access_token: accessToken,
       refresh_token: refreshToken,
       member_id: memberId,
       is_new_member: params.get("is_new_member") === "true",
+      ...emailParam ? { email: emailParam } : {},
       state: params.get("state") || void 0
     };
     if (window.opener) {
@@ -4550,6 +4554,7 @@ var OAuthAPI = class {
       refresh_token: resp.refresh_token,
       member_id: resp.member_id,
       is_new_member: resp.is_new_member,
+      ...resp.email ? { email: resp.email } : {},
       state: params.get("state") || void 0
     };
     if (window.opener) {
@@ -5226,6 +5231,53 @@ var PushAPI = class {
     const prefix = this.getPublicPrefix();
     await this.http.delete(`${prefix}/push/devices/${encodeURIComponent(deviceToken)}`);
   }
+  // ============ Server-side Send (Functions / cb_sk_ 전용) ============
+  /**
+   * 회원 ID 목록으로 푸시 발송 — Functions / cb_sk_ 인증 환경 전용.
+   *
+   * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT 또는 User Secret Key
+   * (`cb_sk_`) 만 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`) 인스턴스에서는 호출
+   * 자체가 차단되며, 권한 누설을 막기 위해 명확한 에러를 던진다.
+   *
+   * @param appId 발송 대상 앱 ID (cb_sk_ 환경은 user 단위 권한이므로 명시 전달).
+   * @param memberIds 받는 회원 ID 배열 (UUID).
+   * @param payload 푸시 내용/옵션.
+   *
+   * @example
+   * ```ts
+   * // ConnectBase Function (Node.js, secrets.CB_SECRET_KEY 주입)
+   * const result = await cb.push.sendToMembers(APP_ID, [memberId], {
+   *     title: '새 알림',
+   *     body: '확인해보세요',
+   *     data: { route: '/notifications' },
+   * })
+   * console.log(result.message_id, result.sent_count)
+   * ```
+   */
+  async sendToMembers(appId, memberIds, payload) {
+    if (this.http.hasPublicKey()) {
+      throw new Error(
+        "cb.push.sendToMembers() \uB294 User Secret Key(cb_sk_) \uB610\uB294 \uCF58\uC194 JWT \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. Public Key(cb_pk_) SDK \uC778\uC2A4\uD134\uC2A4\uB85C\uB294 \uD638\uCD9C\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 Functions \uD658\uACBD\uC5D0\uC11C \uC0AC\uC6A9\uD558\uC138\uC694."
+      );
+    }
+    if (memberIds.length === 0) {
+      throw new Error("cb.push.sendToMembers(): memberIds \uAC00 \uBE44\uC5B4\uC788\uC2B5\uB2C8\uB2E4.");
+    }
+    const body = {
+      target_type: "members",
+      target_member_ids: memberIds,
+      title: payload.title,
+      body: payload.body,
+      ...payload.imageUrl !== void 0 ? { image_url: payload.imageUrl } : {},
+      ...payload.data !== void 0 ? { data: payload.data } : {},
+      ...payload.platforms !== void 0 ? { platforms: payload.platforms } : {},
+      ...payload.ttlSeconds !== void 0 ? { ttl: payload.ttlSeconds } : {},
+      ...payload.priority !== void 0 ? { priority: payload.priority } : {},
+      ...payload.clickAction !== void 0 ? { click_action: payload.clickAction } : {},
+      ...payload.scheduledAt !== void 0 ? { scheduled_at: payload.scheduledAt } : {}
+    };
+    return this.http.post(`/v1/apps/${appId}/push/send`, body);
+  }
   // ============ Helper Methods ============
   /**
    * 브라우저 고유 ID 생성 (localStorage에 저장)
@@ -8135,6 +8187,15 @@ var SessionManager = class {
     return generateId();
   }
 };
+function buildAnalyticsQuery(options) {
+  if (!options) return "";
+  const params = new URLSearchParams();
+  if (options.start_date !== void 0) params.set("start_date", String(options.start_date));
+  if (options.end_date !== void 0) params.set("end_date", String(options.end_date));
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
 function parseUTM() {
   if (typeof window === "undefined") return {};
   try {
@@ -8285,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;
@@ -8310,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;
@@ -8403,6 +8499,120 @@ var AnalyticsAPI = class {
   async flush() {
     await this.flushQueue();
   }
+  /**
+   * 인기 페이지 조회 (콘솔 JWT 또는 User Secret Key `cb_sk_` 인증 필요).
+   *
+   * 브라우저 환경에서 Public Key(`cb_pk_`) 만 가진 SDK 인스턴스로는 호출이 차단된다.
+   * Functions / 어드민 앱 등 cb_sk_ 환경에서 사용하라.
+   *
+   * @param storageWebId 조회할 웹스토리지 ID. 미지정 시 `init()` 에 전달된 ID 사용.
+   * @param options 기간/limit 옵션
+   * @example
+   * ```ts
+   * const { pages } = await cb.analytics.getPopularPages('019d8...', { limit: 20 })
+   * ```
+   */
+  async getPopularPages(storageWebId, options) {
+    const id = this.requireServerSideStorageId(storageWebId, "getPopularPages");
+    const qs = buildAnalyticsQuery(options);
+    return this.http.get(`/v1/storages/web/${id}/popular-pages${qs}`);
+  }
+  /**
+   * 페이지 전환 플로우(Sankey) 조회 — JWT/cb_sk_ 인증 필요.
+   */
+  async getNavigationFlow(storageWebId, options) {
+    const id = this.requireServerSideStorageId(storageWebId, "getNavigationFlow");
+    const qs = buildAnalyticsQuery(options);
+    return this.http.get(`/v1/storages/web/${id}/navigation/flow${qs}`);
+  }
+  /**
+   * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
+   */
+  async getVisitors(storageWebId, options) {
+    const id = this.requireServerSideStorageId(storageWebId, "getVisitors");
+    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}/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_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.
+   */
+  requireServerSideStorageId(storageWebId, methodName) {
+    if (this.http.hasPublicKey()) {
+      throw new Error(
+        `cb.analytics.${methodName}() \uB294 \uCF58\uC194 JWT \uB610\uB294 User Secret Key(cb_sk_) \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. \uBE0C\uB77C\uC6B0\uC800 SDK \uC758 Public Key(cb_pk_) \uB85C\uB294 \uD638\uCD9C\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 Functions \uD658\uACBD\uC5D0\uC11C \uC0AC\uC6A9\uD558\uC138\uC694.`
+      );
+    }
+    const id = storageWebId ?? this.storageWebId;
+    if (!id) {
+      throw new Error(`cb.analytics.${methodName}() \uD638\uCD9C \uC2DC storageWebId \uAC00 \uD544\uC694\uD569\uB2C8\uB2E4 (init \uB610\uB294 \uC778\uC790\uB85C \uC804\uB2EC).`);
+    }
+    return id;
+  }
   /**
    * 세션 매니저 접근 (고급 사용자용).
    *

package/package.json

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