connectbase-client 1.9.0 → 1.10.0

package/dist/index.d.mts

@@ -172,6 +172,77 @@ interface AnalyticsEvent {
     properties?: Record<string, unknown>;
     timestamp?: number;
 }
+/**
+ * 인기 페이지 목록 응답.
+ *
+ * 백엔드 `dto.PopularPagesResponse` 와 1:1 매핑.
+ */
+interface PopularPagesResponse {
+    pages: Array<{
+        page_path: string;
+        page_views: number;
+    }>;
+    start_date: number;
+    end_date: number;
+}
+/**
+ * 방문자 목록 응답.
+ *
+ * 백엔드 `dto.VisitorListResponse` 와 1:1 매핑. `app_member_id` 는 게스트 방문자에는
+ * 없을 수 있다.
+ */
+interface VisitorListResponse {
+    visitors: Array<{
+        id: string;
+        visitor_uid: string;
+        app_member_id?: string;
+        total_visits: number;
+        total_page_views: number;
+        referrer?: string;
+        last_ip?: string;
+        country?: string;
+        is_bot: boolean;
+        first_visit_at: string;
+        last_visit_at: string;
+    }>;
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+/**
+ * 페이지 전환 플로우(Sankey) 응답.
+ *
+ * 백엔드 `dto.NavigationFlowResponse` 와 1:1 매핑. `nodes` 는 페이지, `links` 는 전환.
+ */
+interface NavigationFlowResponse {
+    nodes: Array<{
+        id: string;
+        label: string;
+        value: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        value: number;
+    }>;
+}
+/**
+ * 조회 메서드 공통 옵션.
+ *
+ * `start_date` / `end_date` 는 백엔드가 정수형 epoch-day 또는 yyyymmdd 로 다루는 값
+ * (서비스 메서드 시그니처 기준 int). 0 또는 미지정 시 기본 기간을 사용.
+ */
+interface AnalyticsRangeOptions {
+    start_date?: number;
+    end_date?: number;
+    limit?: number;
+}
+interface VisitorListOptions {
+    limit?: number;
+    offset?: number;
+    sort_by?: 'last_visit' | 'total_visits' | 'total_page_views';
+}
 declare class SessionManager {
     private _sessionId;
     private _visitorUid;
@@ -270,6 +341,33 @@ declare class AnalyticsAPI {
      * ```
      */
     flush(): Promise<void>;
+    /**
+     * 인기 페이지 조회 (콘솔 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 })
+     * ```
+     */
+    getPopularPages(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<PopularPagesResponse>;
+    /**
+     * 페이지 전환 플로우(Sankey) 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getNavigationFlow(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<NavigationFlowResponse>;
+    /**
+     * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getVisitors(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorListResponse>;
+    /**
+     * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
+     * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.
+     */
+    private requireServerSideStorageId;
     /**
      * 세션 매니저 접근 (고급 사용자용).
      *
@@ -3174,12 +3272,17 @@ interface GetAuthorizationURLResponse {
 }
 /**
  * OAuth 콜백 응답
+ *
+ * `email` 은 1.10 부터 추가된 선택적 필드. Apple private relay 또는 이메일 권한 미동의
+ * 시 빈 문자열 / undefined 일 수 있다. 값이 있으면 첫 로그인 시점에 이메일을 확보할 수 있어
+ * 별도 `getMember()` 호출이 불필요하다.
  */
 interface OAuthCallbackResponse {
     member_id: string;
     access_token: string;
     refresh_token: string;
     is_new_member: boolean;
+    email?: string;
 }
 
 /**
@@ -3284,6 +3387,7 @@ declare class OAuthAPI {
         refresh_token?: string;
         member_id?: string;
         is_new_member?: boolean;
+        email?: string;
         state?: string;
         error?: string;
     } | null;
@@ -3308,6 +3412,7 @@ declare class OAuthAPI {
         refresh_token: string;
         member_id: string;
         is_new_member: boolean;
+        email?: string;
         state?: string;
     } | null>;
 }
@@ -4095,6 +4200,35 @@ interface WebPushSubscription {
     };
 }
 
+/**
+ * `cb.push.sendToMembers` 페이로드. 백엔드 `dto.SendPushRequest` 의 멤버 발송 케이스
+ * 에 매핑되며, target_type / target_member_ids 는 SDK 가 자동 채운다.
+ */
+interface SendToMembersPayload {
+    title: string;
+    body: string;
+    imageUrl?: string;
+    data?: Record<string, unknown>;
+    /** 'ios' | 'android' | 'web' 중 선택. 빈 배열/미지정 시 전체 플랫폼 발송. */
+    platforms?: Array<'ios' | 'android' | 'web'>;
+    /** TTL(초). 기본 86400 (24h). */
+    ttlSeconds?: number;
+    priority?: 'normal' | 'high';
+    clickAction?: string;
+    /** ISO8601 형식 예약 발송 시각. 미지정 시 즉시 발송. */
+    scheduledAt?: string;
+}
+/**
+ * 발송 결과. 백엔드 `dto.SendResultResponse` 와 1:1 매핑.
+ */
+interface SendPushResult {
+    message_id: string;
+    total_target: number;
+    sent_count: number;
+    failed_count: number;
+    status: string;
+    error_message?: string;
+}
 /**
  * 푸시 알림 API
  *
@@ -4233,6 +4367,29 @@ declare class PushAPI {
      * @param deviceToken Web Push endpoint URL (등록 시 사용한 endpoint)
      */
     unregisterWebPush(deviceToken: string): Promise<void>;
+    /**
+     * 회원 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)
+     * ```
+     */
+    sendToMembers(appId: string, memberIds: string[], payload: SendToMembersPayload): Promise<SendPushResult>;
     /**
      * 브라우저 고유 ID 생성 (localStorage에 저장)
      */
@@ -6714,10 +6871,10 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'localStorage': 브라우저 종료 후에도 유지 (기본값)
-     * - 'sessionStorage': 탭 종료 시 삭제
-     * - 'none': 메모리에만 저장 (페이지 새로고침 시 삭제)
-     * @default 'localStorage'
+     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * @default 'none'
      */
     persistence?: TokenPersistence;
     /**

package/dist/index.d.ts

@@ -172,6 +172,77 @@ interface AnalyticsEvent {
     properties?: Record<string, unknown>;
     timestamp?: number;
 }
+/**
+ * 인기 페이지 목록 응답.
+ *
+ * 백엔드 `dto.PopularPagesResponse` 와 1:1 매핑.
+ */
+interface PopularPagesResponse {
+    pages: Array<{
+        page_path: string;
+        page_views: number;
+    }>;
+    start_date: number;
+    end_date: number;
+}
+/**
+ * 방문자 목록 응답.
+ *
+ * 백엔드 `dto.VisitorListResponse` 와 1:1 매핑. `app_member_id` 는 게스트 방문자에는
+ * 없을 수 있다.
+ */
+interface VisitorListResponse {
+    visitors: Array<{
+        id: string;
+        visitor_uid: string;
+        app_member_id?: string;
+        total_visits: number;
+        total_page_views: number;
+        referrer?: string;
+        last_ip?: string;
+        country?: string;
+        is_bot: boolean;
+        first_visit_at: string;
+        last_visit_at: string;
+    }>;
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+/**
+ * 페이지 전환 플로우(Sankey) 응답.
+ *
+ * 백엔드 `dto.NavigationFlowResponse` 와 1:1 매핑. `nodes` 는 페이지, `links` 는 전환.
+ */
+interface NavigationFlowResponse {
+    nodes: Array<{
+        id: string;
+        label: string;
+        value: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        value: number;
+    }>;
+}
+/**
+ * 조회 메서드 공통 옵션.
+ *
+ * `start_date` / `end_date` 는 백엔드가 정수형 epoch-day 또는 yyyymmdd 로 다루는 값
+ * (서비스 메서드 시그니처 기준 int). 0 또는 미지정 시 기본 기간을 사용.
+ */
+interface AnalyticsRangeOptions {
+    start_date?: number;
+    end_date?: number;
+    limit?: number;
+}
+interface VisitorListOptions {
+    limit?: number;
+    offset?: number;
+    sort_by?: 'last_visit' | 'total_visits' | 'total_page_views';
+}
 declare class SessionManager {
     private _sessionId;
     private _visitorUid;
@@ -270,6 +341,33 @@ declare class AnalyticsAPI {
      * ```
      */
     flush(): Promise<void>;
+    /**
+     * 인기 페이지 조회 (콘솔 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 })
+     * ```
+     */
+    getPopularPages(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<PopularPagesResponse>;
+    /**
+     * 페이지 전환 플로우(Sankey) 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getNavigationFlow(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<NavigationFlowResponse>;
+    /**
+     * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getVisitors(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorListResponse>;
+    /**
+     * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
+     * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.
+     */
+    private requireServerSideStorageId;
     /**
      * 세션 매니저 접근 (고급 사용자용).
      *
@@ -3174,12 +3272,17 @@ interface GetAuthorizationURLResponse {
 }
 /**
  * OAuth 콜백 응답
+ *
+ * `email` 은 1.10 부터 추가된 선택적 필드. Apple private relay 또는 이메일 권한 미동의
+ * 시 빈 문자열 / undefined 일 수 있다. 값이 있으면 첫 로그인 시점에 이메일을 확보할 수 있어
+ * 별도 `getMember()` 호출이 불필요하다.
  */
 interface OAuthCallbackResponse {
     member_id: string;
     access_token: string;
     refresh_token: string;
     is_new_member: boolean;
+    email?: string;
 }
 
 /**
@@ -3284,6 +3387,7 @@ declare class OAuthAPI {
         refresh_token?: string;
         member_id?: string;
         is_new_member?: boolean;
+        email?: string;
         state?: string;
         error?: string;
     } | null;
@@ -3308,6 +3412,7 @@ declare class OAuthAPI {
         refresh_token: string;
         member_id: string;
         is_new_member: boolean;
+        email?: string;
         state?: string;
     } | null>;
 }
@@ -4095,6 +4200,35 @@ interface WebPushSubscription {
     };
 }
 
+/**
+ * `cb.push.sendToMembers` 페이로드. 백엔드 `dto.SendPushRequest` 의 멤버 발송 케이스
+ * 에 매핑되며, target_type / target_member_ids 는 SDK 가 자동 채운다.
+ */
+interface SendToMembersPayload {
+    title: string;
+    body: string;
+    imageUrl?: string;
+    data?: Record<string, unknown>;
+    /** 'ios' | 'android' | 'web' 중 선택. 빈 배열/미지정 시 전체 플랫폼 발송. */
+    platforms?: Array<'ios' | 'android' | 'web'>;
+    /** TTL(초). 기본 86400 (24h). */
+    ttlSeconds?: number;
+    priority?: 'normal' | 'high';
+    clickAction?: string;
+    /** ISO8601 형식 예약 발송 시각. 미지정 시 즉시 발송. */
+    scheduledAt?: string;
+}
+/**
+ * 발송 결과. 백엔드 `dto.SendResultResponse` 와 1:1 매핑.
+ */
+interface SendPushResult {
+    message_id: string;
+    total_target: number;
+    sent_count: number;
+    failed_count: number;
+    status: string;
+    error_message?: string;
+}
 /**
  * 푸시 알림 API
  *
@@ -4233,6 +4367,29 @@ declare class PushAPI {
      * @param deviceToken Web Push endpoint URL (등록 시 사용한 endpoint)
      */
     unregisterWebPush(deviceToken: string): Promise<void>;
+    /**
+     * 회원 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)
+     * ```
+     */
+    sendToMembers(appId: string, memberIds: string[], payload: SendToMembersPayload): Promise<SendPushResult>;
     /**
      * 브라우저 고유 ID 생성 (localStorage에 저장)
      */
@@ -6714,10 +6871,10 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'localStorage': 브라우저 종료 후에도 유지 (기본값)
-     * - 'sessionStorage': 탭 종료 시 삭제
-     * - 'none': 메모리에만 저장 (페이지 새로고침 시 삭제)
-     * @default 'localStorage'
+     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * @default 'none'
      */
     persistence?: TokenPersistence;
     /**

package/dist/index.js

@@ -4474,11 +4474,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);
@@ -4546,11 +4548,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) {
@@ -4588,6 +4592,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) {
@@ -5264,6 +5269,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에 저장)
@@ -8173,6 +8225,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 {
@@ -8441,6 +8502,60 @@ 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}`);
+  }
+  /**
+   * 조회 메서드 공통 가드 — 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;
+  }
   /**
    * 세션 매니저 접근 (고급 사용자용).
    *