connectbase-client 1.8.1 → 1.9.1

package/dist/index.d.mts

@@ -13,6 +13,11 @@ declare class AuthError extends Error {
     constructor(message: string);
 }
 
+interface AbortOptions {
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
 type TokenPersistence = 'localStorage' | 'sessionStorage' | 'none';
 interface HttpClientConfig {
     baseUrl: string;
@@ -39,6 +44,16 @@ interface HttpClientConfig {
      * - 'localStorage': 브라우저 종료 후에도 유지. JS 접근 가능 → XSS 로 영구 탈취 가능
      */
     persistence?: TokenPersistence;
+    /**
+     * 요청별 기본 타임아웃(ms). 개별 호출의 `timeout` 이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 ApiError/AuthError 발생 시 호출된다.
+     * 운영 관측성(Sentry/Datadog/자체 엔드포인트)과 연결하기 위한 훅.
+     */
+    onError?: (error: ApiError | AuthError) => void;
     onTokenRefresh?: (tokens: {
         accessToken: string;
         refreshToken: string;
@@ -46,7 +61,7 @@ interface HttpClientConfig {
     onAuthError?: (error: AuthError) => void;
     onTokenExpired?: () => void;
 }
-interface RequestConfig {
+interface RequestConfig extends AbortOptions {
     skipAuth?: boolean;
     headers?: Record<string, string>;
 }
@@ -55,6 +70,8 @@ declare class HttpClient {
     private isRefreshing;
     private refreshPromise;
     private storageKey;
+    private refreshFailureCount;
+    private refreshLockedUntil;
     constructor(config: HttpClientConfig);
     private warnIfUnsafePersistence;
     updateConfig(config: Partial<HttpClientConfig>): void;
@@ -104,9 +121,14 @@ declare class HttpClient {
      */
     getBaseUrl(): string;
     private refreshAccessToken;
+    private emitError;
     private isTokenExpired;
     private prepareHeaders;
     private handleResponse;
+    /**
+     * AbortController 를 관리하며 fetch 호출을 실행. 타임아웃/외부 signal 병합.
+     */
+    private doFetch;
     get<T>(url: string, config?: RequestConfig): Promise<T>;
     post<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
     put<T>(url: string, data: unknown, config?: RequestConfig): Promise<T>;
@@ -114,7 +136,8 @@ declare class HttpClient {
     delete<T>(url: string, config?: RequestConfig): Promise<T>;
     /**
      * Raw fetch 요청 (SSE 스트리밍 등에 사용)
-     * 인증 헤더가 자동으로 추가됩니다.
+     * 인증 헤더가 자동으로 추가됩니다. timeout 은 호출자가 직접 signal 로 관리해야 합니다
+     * (스트리밍 특성상 전역 timeout 을 강제하지 않음).
      */
     fetchRaw(url: string, init?: RequestInit): Promise<Response>;
 }
@@ -230,9 +253,31 @@ declare class AnalyticsAPI {
      * 세션 heartbeat 자동 전송 시작 (30초 간격)
      */
     enableHeartbeat(): void;
-    /** 큐에 있는 이벤트 즉시 전송 */
+    /**
+     * 큐에 있는 이벤트 즉시 전송.
+     *
+     * 기본적으로 이벤트는 배치(10개) 또는 주기(5초)로 flush 되지만, 페이지 이탈 직전이나
+     * 결정적 이벤트(결제 완료 등)는 수동으로 `flush()` 를 호출해 전송 지연을 줄일 수 있다.
+     *
+     * @returns 서버 응답 완료 시까지 대기하는 Promise
+     *
+     * @example
+     * ```ts
+     * // 결제 완료 직후 이탈에 대비해 즉시 flush
+     * await cb.analytics.track('purchase_completed', { order_id: '123' })
+     * await cb.analytics.flush()
+     * window.location.href = '/thank-you'
+     * ```
+     */
     flush(): Promise<void>;
-    /** 세션 매니저 접근 (고급) */
+    /**
+     * 세션 매니저 접근 (고급 사용자용).
+     *
+     * 외부에서 세션 ID 를 읽어 자체 로깅에 합치거나 강제 세션 종료/재시작이 필요한 경우
+     * 사용. 일반적으로는 AnalyticsAPI 가 내부적으로 세션을 관리하므로 호출할 필요가 없다.
+     *
+     * @returns 내부 SessionManager 인스턴스
+     */
     getSession(): SessionManager;
     private canTrack;
     private isDNT;
@@ -1864,6 +1909,12 @@ declare class StorageAPI {
      * API Key 인증 시 /v1/public 접두사 반환
      */
     private getPublicPrefix;
+    /**
+     * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
+     * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
+     * 타임아웃과 외부 signal 을 모두 지원한다.
+     */
+    private uploadToPresigned;
     /**
      * 파일 목록 조회
      *
@@ -2735,6 +2786,12 @@ declare class RealtimeAPI {
     onReadReceipt(category: string, handler: ReadReceiptHandler): () => void;
     private doConnect;
     private log;
+    /**
+     * 에러 로그. `options.debug` 가 true 일 때만 console 에 출력.
+     * 운영 환경에서는 소비자 애플리케이션의 `ConnectBase({ onError })` 또는
+     * `cb.errorTracker` 로 전달하는 것을 권장하므로 SDK 자체 console 출력은 opt-in.
+     */
+    private logError;
     private handleServerMessage;
     private handleDisconnect;
     /**
@@ -4509,7 +4566,29 @@ declare class VideoAPI {
      */
     waitForReady(videoId: string, options?: WaitOptions): Promise<Video>;
     /**
-     * List videos
+     * 영상 목록 조회.
+     *
+     * 필터링/페이지네이션 옵션을 조합해 조건에 맞는 영상들을 반환한다.
+     * API Key(publicKey) 또는 JWT 인증이 모두 지원되며, publicKey 로는 공개 영상만 노출된다.
+     *
+     * @param options - 필터/페이지네이션 옵션
+     * @param options.status - `uploading` | `processing` | `ready` | `failed`
+     * @param options.visibility - `public` | `unlisted` | `private` | `members`
+     * @param options.search - 제목 부분 일치 검색
+     * @param options.channel_id - 특정 채널로 한정
+     * @param options.page - 1 부터 시작
+     * @param options.limit - 기본 20, 최대 100
+     * @returns `videos` 배열과 `total` 카운트를 포함하는 응답
+     *
+     * @example
+     * ```ts
+     * // 내 채널의 최근 공개 영상 10개
+     * const { videos, total } = await cb.video.list({
+     *   channel_id: 'ch_abc',
+     *   visibility: 'public',
+     *   limit: 10,
+     * })
+     * ```
      */
     list(options?: VideoListOptions): Promise<VideoListResponse>;
     /**
@@ -4525,7 +4604,20 @@ declare class VideoAPI {
      */
     delete(videoId: string): Promise<void>;
     /**
-     * Get streaming URL for a video
+     * 영상 스트리밍 URL 획득 (HLS manifest 권장).
+     *
+     * 반환된 URL 은 `hls.js` 또는 Safari 네이티브 HLS 플레이어에 그대로 전달 가능하다.
+     * 서명된 URL 이므로 만료 시간이 존재하며, 갱신이 필요한 경우 다시 호출한다.
+     *
+     * @param videoId - 대상 영상 ID
+     * @param quality - `auto` (기본) | `1080p` | `720p` | `480p` | `360p` 등 트랜스코딩된 품질 레벨
+     * @returns HLS manifest URL 과 만료 정보
+     *
+     * @example
+     * ```ts
+     * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
+     * videoElement.src = url
+     * ```
      */
     getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
     /**
@@ -6622,16 +6714,34 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'localStorage': 브라우저 종료 후에도 유지 (기본값)
-     * - 'sessionStorage': 탭 종료 시 삭제
-     * - 'none': 메모리에만 저장 (페이지 새로고침 시 삭제)
-     * @default 'localStorage'
+     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * @default 'none'
      */
     persistence?: TokenPersistence;
     /**
      * 에러 트래커 설정
      */
     errorTracker?: ErrorTrackerConfig;
+    /**
+     * 기본 요청 타임아웃(ms). 개별 호출의 `timeout` 이 지정되면 해당 값이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 `ApiError` / `AuthError` 발생 시 호출됩니다.
+     * Sentry/Datadog 등 관측성 파이프라인과 연결하기 위한 훅.
+     *
+     * @example
+     * ```ts
+     * const cb = new ConnectBase({
+     *   publicKey: '...',
+     *   onError: (err) => Sentry.captureException(err),
+     * })
+     * ```
+     */
+    onError?: (error: ApiError | AuthError) => void;
 }
 /**
  * Connect Base SDK

package/dist/index.d.ts

@@ -13,6 +13,11 @@ declare class AuthError extends Error {
     constructor(message: string);
 }
 
+interface AbortOptions {
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
 type TokenPersistence = 'localStorage' | 'sessionStorage' | 'none';
 interface HttpClientConfig {
     baseUrl: string;
@@ -39,6 +44,16 @@ interface HttpClientConfig {
      * - 'localStorage': 브라우저 종료 후에도 유지. JS 접근 가능 → XSS 로 영구 탈취 가능
      */
     persistence?: TokenPersistence;
+    /**
+     * 요청별 기본 타임아웃(ms). 개별 호출의 `timeout` 이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 ApiError/AuthError 발생 시 호출된다.
+     * 운영 관측성(Sentry/Datadog/자체 엔드포인트)과 연결하기 위한 훅.
+     */
+    onError?: (error: ApiError | AuthError) => void;
     onTokenRefresh?: (tokens: {
         accessToken: string;
         refreshToken: string;
@@ -46,7 +61,7 @@ interface HttpClientConfig {
     onAuthError?: (error: AuthError) => void;
     onTokenExpired?: () => void;
 }
-interface RequestConfig {
+interface RequestConfig extends AbortOptions {
     skipAuth?: boolean;
     headers?: Record<string, string>;
 }
@@ -55,6 +70,8 @@ declare class HttpClient {
     private isRefreshing;
     private refreshPromise;
     private storageKey;
+    private refreshFailureCount;
+    private refreshLockedUntil;
     constructor(config: HttpClientConfig);
     private warnIfUnsafePersistence;
     updateConfig(config: Partial<HttpClientConfig>): void;
@@ -104,9 +121,14 @@ declare class HttpClient {
      */
     getBaseUrl(): string;
     private refreshAccessToken;
+    private emitError;
     private isTokenExpired;
     private prepareHeaders;
     private handleResponse;
+    /**
+     * AbortController 를 관리하며 fetch 호출을 실행. 타임아웃/외부 signal 병합.
+     */
+    private doFetch;
     get<T>(url: string, config?: RequestConfig): Promise<T>;
     post<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
     put<T>(url: string, data: unknown, config?: RequestConfig): Promise<T>;
@@ -114,7 +136,8 @@ declare class HttpClient {
     delete<T>(url: string, config?: RequestConfig): Promise<T>;
     /**
      * Raw fetch 요청 (SSE 스트리밍 등에 사용)
-     * 인증 헤더가 자동으로 추가됩니다.
+     * 인증 헤더가 자동으로 추가됩니다. timeout 은 호출자가 직접 signal 로 관리해야 합니다
+     * (스트리밍 특성상 전역 timeout 을 강제하지 않음).
      */
     fetchRaw(url: string, init?: RequestInit): Promise<Response>;
 }
@@ -230,9 +253,31 @@ declare class AnalyticsAPI {
      * 세션 heartbeat 자동 전송 시작 (30초 간격)
      */
     enableHeartbeat(): void;
-    /** 큐에 있는 이벤트 즉시 전송 */
+    /**
+     * 큐에 있는 이벤트 즉시 전송.
+     *
+     * 기본적으로 이벤트는 배치(10개) 또는 주기(5초)로 flush 되지만, 페이지 이탈 직전이나
+     * 결정적 이벤트(결제 완료 등)는 수동으로 `flush()` 를 호출해 전송 지연을 줄일 수 있다.
+     *
+     * @returns 서버 응답 완료 시까지 대기하는 Promise
+     *
+     * @example
+     * ```ts
+     * // 결제 완료 직후 이탈에 대비해 즉시 flush
+     * await cb.analytics.track('purchase_completed', { order_id: '123' })
+     * await cb.analytics.flush()
+     * window.location.href = '/thank-you'
+     * ```
+     */
     flush(): Promise<void>;
-    /** 세션 매니저 접근 (고급) */
+    /**
+     * 세션 매니저 접근 (고급 사용자용).
+     *
+     * 외부에서 세션 ID 를 읽어 자체 로깅에 합치거나 강제 세션 종료/재시작이 필요한 경우
+     * 사용. 일반적으로는 AnalyticsAPI 가 내부적으로 세션을 관리하므로 호출할 필요가 없다.
+     *
+     * @returns 내부 SessionManager 인스턴스
+     */
     getSession(): SessionManager;
     private canTrack;
     private isDNT;
@@ -1864,6 +1909,12 @@ declare class StorageAPI {
      * API Key 인증 시 /v1/public 접두사 반환
      */
     private getPublicPrefix;
+    /**
+     * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
+     * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
+     * 타임아웃과 외부 signal 을 모두 지원한다.
+     */
+    private uploadToPresigned;
     /**
      * 파일 목록 조회
      *
@@ -2735,6 +2786,12 @@ declare class RealtimeAPI {
     onReadReceipt(category: string, handler: ReadReceiptHandler): () => void;
     private doConnect;
     private log;
+    /**
+     * 에러 로그. `options.debug` 가 true 일 때만 console 에 출력.
+     * 운영 환경에서는 소비자 애플리케이션의 `ConnectBase({ onError })` 또는
+     * `cb.errorTracker` 로 전달하는 것을 권장하므로 SDK 자체 console 출력은 opt-in.
+     */
+    private logError;
     private handleServerMessage;
     private handleDisconnect;
     /**
@@ -4509,7 +4566,29 @@ declare class VideoAPI {
      */
     waitForReady(videoId: string, options?: WaitOptions): Promise<Video>;
     /**
-     * List videos
+     * 영상 목록 조회.
+     *
+     * 필터링/페이지네이션 옵션을 조합해 조건에 맞는 영상들을 반환한다.
+     * API Key(publicKey) 또는 JWT 인증이 모두 지원되며, publicKey 로는 공개 영상만 노출된다.
+     *
+     * @param options - 필터/페이지네이션 옵션
+     * @param options.status - `uploading` | `processing` | `ready` | `failed`
+     * @param options.visibility - `public` | `unlisted` | `private` | `members`
+     * @param options.search - 제목 부분 일치 검색
+     * @param options.channel_id - 특정 채널로 한정
+     * @param options.page - 1 부터 시작
+     * @param options.limit - 기본 20, 최대 100
+     * @returns `videos` 배열과 `total` 카운트를 포함하는 응답
+     *
+     * @example
+     * ```ts
+     * // 내 채널의 최근 공개 영상 10개
+     * const { videos, total } = await cb.video.list({
+     *   channel_id: 'ch_abc',
+     *   visibility: 'public',
+     *   limit: 10,
+     * })
+     * ```
      */
     list(options?: VideoListOptions): Promise<VideoListResponse>;
     /**
@@ -4525,7 +4604,20 @@ declare class VideoAPI {
      */
     delete(videoId: string): Promise<void>;
     /**
-     * Get streaming URL for a video
+     * 영상 스트리밍 URL 획득 (HLS manifest 권장).
+     *
+     * 반환된 URL 은 `hls.js` 또는 Safari 네이티브 HLS 플레이어에 그대로 전달 가능하다.
+     * 서명된 URL 이므로 만료 시간이 존재하며, 갱신이 필요한 경우 다시 호출한다.
+     *
+     * @param videoId - 대상 영상 ID
+     * @param quality - `auto` (기본) | `1080p` | `720p` | `480p` | `360p` 등 트랜스코딩된 품질 레벨
+     * @returns HLS manifest URL 과 만료 정보
+     *
+     * @example
+     * ```ts
+     * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
+     * videoElement.src = url
+     * ```
      */
     getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
     /**
@@ -6622,16 +6714,34 @@ interface ConnectBaseConfig {
     onTokenExpired?: () => void;
     /**
      * 토큰 저장 방식.
-     * - 'localStorage': 브라우저 종료 후에도 유지 (기본값)
-     * - 'sessionStorage': 탭 종료 시 삭제
-     * - 'none': 메모리에만 저장 (페이지 새로고침 시 삭제)
-     * @default 'localStorage'
+     * - 'none' (기본·권장): 메모리에만 저장. 새로고침 시 재로그인 필요. XSS 노출 최소화
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 현재 탭 세션 탈취 가능)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 토큰 영구 탈취 가능 — 콘솔 경고 출력)
+     * @default 'none'
      */
     persistence?: TokenPersistence;
     /**
      * 에러 트래커 설정
      */
     errorTracker?: ErrorTrackerConfig;
+    /**
+     * 기본 요청 타임아웃(ms). 개별 호출의 `timeout` 이 지정되면 해당 값이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 `ApiError` / `AuthError` 발생 시 호출됩니다.
+     * Sentry/Datadog 등 관측성 파이프라인과 연결하기 위한 훅.
+     *
+     * @example
+     * ```ts
+     * const cb = new ConnectBase({
+     *   publicKey: '...',
+     *   onError: (err) => Sentry.captureException(err),
+     * })
+     * ```
+     */
+    onError?: (error: ApiError | AuthError) => void;
 }
 /**
  * Connect Base SDK