@vircle/sdk-web 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,701 @@
+import { VircleCore, VircleConfig, VircleCoreOptions, EventContext, DeviceContext, PageContext, AppContext, StorageAdapter } from '@vircle/sdk-core-ts';
+export { AppContext, DeviceContext, EventContext, PageContext, StorageAdapter, UserProperties, VircleConfig } from '@vircle/sdk-core-ts';
+
+interface VircleWebConfig extends VircleConfig {
+    /**
+     * 자동 페이지뷰 추적 활성화
+     */
+    trackPageViews?: boolean;
+    /**
+     * 자동 클릭 추적 활성화
+     */
+    trackClicks?: boolean;
+    /**
+     * 자동 폼 제출 추적 활성화
+     */
+    trackForms?: boolean;
+    /**
+     * 자동 에러 추적 활성화
+     */
+    trackErrors?: boolean;
+    /**
+     * 싱글 페이지 앱 모드
+     */
+    singlePageApp?: boolean;
+    /**
+     * 커스텀 스토리지 키 접두사
+     */
+    storagePrefix?: string;
+}
+interface VircleWebOptions extends Partial<VircleCoreOptions> {
+    /**
+     * 페이지 언로드 시 이벤트 플러시
+     */
+    flushOnUnload?: boolean;
+    /**
+     * 컨텍스트 캐싱 시간 (ms)
+     */
+    contextCacheTime?: number;
+    /**
+     * 성능 측정 활성화
+     */
+    enablePerformance?: boolean;
+}
+/**
+ * Web 플랫폼용 Vircle SDK
+ *
+ * @example
+ * ```typescript
+ * const vircle = new VircleWeb({
+ *   apiKey: 'your-api-key',
+ *   trackPageViews: true,
+ *   trackErrors: true
+ * })
+ *
+ * await vircle.initialize()
+ * ```
+ */
+declare class VircleWeb extends VircleCore {
+    private contextCollector;
+    private webConfig;
+    private webOptions;
+    private performanceTracker?;
+    private pageViewTracked;
+    private errorHandler?;
+    private unhandledRejectionHandler?;
+    private clickHandler?;
+    private submitHandler?;
+    private popstateHandler?;
+    private unloadHandler?;
+    constructor(config: VircleWebConfig, options?: VircleWebOptions);
+    /**
+     * SDK 초기화 및 자동 추적 설정
+     *
+     * @description
+     * SDK를 초기화하고 설정에 따라 자동 추적 기능을 활성화합니다.
+     * 페이지뷰, 에러, 클릭, 폼 제출 등의 자동 추적을 설정할 수 있습니다.
+     *
+     * @example
+     * ```typescript
+     * const vircle = new VircleWeb({
+     *   apiKey: 'your-api-key',
+     *   trackPageViews: true,
+     *   trackErrors: true
+     * })
+     *
+     * await vircle.initialize()
+     * ```
+     *
+     * @throws {VircleInitializationError} 초기화 실패 시
+     * @returns {Promise<void>}
+     */
+    initialize(): Promise<void>;
+    /**
+     * 페이지뷰 추적
+     *
+     * @description
+     * 현재 페이지의 방문을 추적합니다. URL, 제목, 리퍼러 등의 정보를 자동으로 수집합니다.
+     *
+     * @example
+     * ```typescript
+     * // 기본 페이지뷰 추적
+     * await vircle.trackPageView()
+     *
+     * // 추가 속성과 함께 추적
+     * await vircle.trackPageView({
+     *   category: 'blog',
+     *   author: 'john.doe'
+     * })
+     * ```
+     *
+     * @param {Record<string, unknown>} [properties] - 추가 속성
+     * @param {EventContext} [context] - 추가 컨텍스트
+     * @returns {Promise<void>}
+     */
+    trackPageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void>;
+    /**
+     * 웹 환경에 최적화된 이벤트 추적
+     * AIDEV-NOTE: 이제 코어의 TaskScheduler를 사용하여 requestIdleCallback 기반의
+     * 일관된 성능 최적화 구현
+     */
+    track<TProperties extends Record<string, unknown> = Record<string, unknown>>(name: string, properties?: TProperties, context?: EventContext): Promise<void>;
+    /**
+     * 캐시된 컨텍스트 반환 또는 새로 수집
+     *
+     * @description
+     * 컨텍스트 정보를 캐시에서 가져오거나 새로 수집합니다.
+     * 성능 최적화를 위해 캐싱을 사용하며, 중복 수집을 방지합니다.
+     *
+     * @private
+     * @returns {Promise<EventContext>} 이벤트 컨텍스트
+     *
+     * AIDEV-NOTE: 컨텍스트 수집은 DOM 접근이 많아 비용이 높으므로
+     * 캐싱을 통해 성능을 최적화. 중복 수집 방지를 위한 Promise 재사용 구현
+     */
+    private getCachedContext;
+    /**
+     * 자동 추적 설정
+     *
+     * @description
+     * 설정에 따라 다양한 자동 추적 기능을 활성화합니다.
+     * 페이지 언로드 시 플러시, 에러 추적, 클릭 추적, 폼 제출 추적, SPA 라우팅 추적 등을 설정합니다.
+     *
+     * @private
+     */
+    private setupAutoTracking;
+    /**
+     * 에러 추적 설정
+     *
+     * @description
+     * JavaScript 에러와 처리되지 않은 Promise rejection을 자동으로 추적합니다.
+     * 에러 메시지, 파일 위치, 스택 트레이스 등의 정보를 수집합니다.
+     *
+     * @private
+     */
+    private setupErrorTracking;
+    /**
+     * 클릭 추적 설정
+     *
+     * @description
+     * 사용자의 클릭 이벤트를 자동으로 추적합니다.
+     * 링크, 버튼, 입력 필드 등의 의미 있는 요소들의 클릭을 감지합니다.
+     * data-vircle-ignore 속성이 있는 요소는 추적에서 제외됩니다.
+     *
+     * @private
+     */
+    private setupClickTracking;
+    /**
+     * 폼 제출 추적 설정
+     *
+     * @description
+     * HTML 폼의 제출 이벤트를 자동으로 추적합니다.
+     * 폼 ID, 이름, action URL, 메서드 등의 정보를 수집합니다.
+     *
+     * @private
+     */
+    private setupFormTracking;
+    /**
+     * SPA 라우팅 추적 설정
+     *
+     * @description
+     * 싱글 페이지 애플리케이션(SPA)의 라우팅 변경을 감지하고 추적합니다.
+     * History API의 pushState, replaceState를 래핑하고 popstate 이벤트를 수신하여
+     * 클라이언트 사이드 라우팅 변경을 감지합니다.
+     *
+     * @private
+     */
+    private setupSPATracking;
+    /**
+     * 라우트 변경 처리
+     *
+     * @description
+     * SPA에서 라우트가 변경될 때 호출되는 핸들러입니다.
+     * 컨텍스트 캐시를 무효화하고 새로운 페이지뷰를 추적합니다.
+     *
+     * @private
+     */
+    private handleRouteChange;
+    /**
+     * 요소가 추적 대상인지 확인
+     *
+     * @description
+     * HTML 요소가 자동 추적 대상인지 판단합니다.
+     * data-vircle-ignore 속성이 있거나 부모 요소에 해당 속성이 있으면 false를 반환합니다.
+     *
+     * @param {HTMLElement} element - 확인할 HTML 요소
+     * @returns {boolean} 추적 대상 여부
+     * @private
+     */
+    private shouldTrackElement;
+    /**
+     * 요소에서 속성 추출
+     *
+     * @description
+     * HTML 요소에서 추적에 필요한 속성을 추출합니다.
+     * 태그 이름, ID, 클래스, href, 텍스트 내용 등을 수집합니다.
+     *
+     * @param {HTMLElement} element - 속성을 추출할 HTML 요소
+     * @returns {Record<string, unknown>} 추출된 속성 객체
+     * @private
+     */
+    private extractElementProperties;
+    /**
+     * SDK 리소스 정리
+     *
+     * @description
+     * SDK가 사용하는 모든 리소스를 정리합니다.
+     * 이벤트 리스너 제거, 성능 추적 중지, 대기 중인 이벤트 전송 등을 수행합니다.
+     *
+     * @example
+     * ```typescript
+     * // 앱 종료 시 정리
+     * window.addEventListener('beforeunload', async () => {
+     *   await vircle.cleanup()
+     * })
+     * ```
+     *
+     * @throws {Error} 정리 중 오류 발생 시
+     * @returns {Promise<void>}
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 현재 페이지 URL 반환
+     *
+     * @description
+     * 현재 브라우저의 전체 URL을 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const url = vircle.getCurrentUrl()
+     * console.log(url) // https://example.com/path?query=value
+     * ```
+     *
+     * @returns {string} 현재 페이지의 전체 URL
+     */
+    getCurrentUrl(): string;
+    /**
+     * 네트워크 연결 상태 확인
+     *
+     * @description
+     * 브라우저의 온라인/오프라인 상태를 확인합니다.
+     * Navigator.onLine API를 사용하여 네트워크 연결 상태를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * if (vircle.isOnline()) {
+     *   // 온라인 상태에서만 실행할 코드
+     *   await vircle.flush()
+     * }
+     * ```
+     *
+     * @returns {boolean} 온라인 상태 여부
+     */
+    isOnline(): boolean;
+}
+
+/**
+ * 웹 브라우저 환경 정보 수집기
+ */
+declare class WebContextCollector {
+    /**
+     * 전체 컨텍스트 수집
+     * @returns 수집된 컨텍스트
+     */
+    collect(): Promise<EventContext>;
+    /**
+     * 디바이스 정보 수집
+     */
+    collectDeviceContext(): Promise<DeviceContext>;
+    /**
+     * 페이지 정보 수집
+     */
+    collectPageContext(): Promise<PageContext>;
+    /**
+     * 앱 정보 수집
+     */
+    collectAppContext(): Promise<AppContext>;
+    /**
+     * 커스텀 컨텍스트 수집
+     */
+    private collectCustomContext;
+    /**
+     * 디바이스 타입 판별
+     */
+    private getDeviceType;
+    /**
+     * OS 판별
+     */
+    private getOS;
+    /**
+     * OS 버전 추출
+     */
+    private getOSVersion;
+    /**
+     * 브라우저 판별
+     */
+    private getBrowser;
+    /**
+     * 브라우저 버전 추출
+     */
+    private getBrowserVersion;
+    /**
+     * UTM 캠페인 파라미터 추출
+     */
+    private extractCampaignParams;
+    /**
+     * 앱 이름 가져오기 (meta 태그에서)
+     */
+    private getAppName;
+    /**
+     * 앱 버전 가져오기 (meta 태그에서)
+     */
+    private getAppVersion;
+    /**
+     * 환경 판별
+     */
+    private getEnvironment;
+}
+
+/**
+ * 브라우저 LocalStorage를 사용하는 스토리지 어댑터
+ *
+ * @description
+ * 브라우저의 LocalStorage API를 활용하여 데이터를 영구 저장합니다.
+ * LocalStorage를 사용할 수 없는 환경에서는 자동으로 대체 스토리지로 폴백합니다.
+ * 용량 초과 시 자동으로 오래된 항목을 정리하는 LRU 방식을 지원합니다.
+ *
+ * @example
+ * ```typescript
+ * const storage = new LocalStorageAdapter('vircle_')
+ * await storage.set('user_id', '12345')
+ * const userId = await storage.get('user_id')
+ * ```
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private prefix;
+    private isAvailable;
+    constructor(prefix?: string);
+    /**
+     * LocalStorage 사용 가능 여부 확인
+     *
+     * @description
+     * LocalStorage API의 사용 가능 여부를 테스트합니다.
+     * 개인정보 보호 모드나 보안 제한으로 인해 LocalStorage가 비활성화된 경우를 감지합니다.
+     *
+     * @private
+     * @returns {boolean} LocalStorage 사용 가능 여부
+     */
+    private checkAvailability;
+    /**
+     * 키에 접두사 추가
+     *
+     * @description
+     * 키에 접두사를 추가하여 다른 애플리케이션과의 충돌을 방지합니다.
+     *
+     * @param {string} key - 원본 키
+     * @returns {string} 접두사가 추가된 키
+     * @private
+     */
+    private getKey;
+    /**
+     * 값 저장
+     *
+     * @description
+     * LocalStorage에 값을 저장합니다. 자동으로 타임스탬프를 추가하여 LRU 정리를 지원합니다.
+     * 용량 초과 시 자동으로 오래된 항목을 정리한 후 재시도합니다.
+     *
+     * @example
+     * ```typescript
+     * await storage.set('preferences', { theme: 'dark', lang: 'ko' })
+     * ```
+     *
+     * @template T - 저장할 값의 타입
+     * @param {string} key - 키
+     * @param {T} value - 저장할 값
+     * @throws {VircleStorageError} 저장 실패 시
+     * @returns {Promise<void>}
+     */
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /**
+     * 값 가져오기
+     *
+     * @description
+     * LocalStorage에서 값을 가져옵니다. 이전 버전과의 호환성을 지원합니다.
+     *
+     * @example
+     * ```typescript
+     * const preferences = await storage.get<{ theme: string }>('preferences')
+     * if (preferences) {
+     *   console.log(preferences.theme)
+     * }
+     * ```
+     *
+     * @template T - 반환할 값의 타입
+     * @param {string} key - 키
+     * @returns {Promise<T | null>} 저장된 값 또는 null
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * 값 삭제
+     *
+     * @description
+     * LocalStorage에서 특정 키의 값을 삭제합니다.
+     *
+     * @example
+     * ```typescript
+     * const removed = await storage.remove('old_data')
+     * console.log(removed ? '삭제 성공' : '키가 존재하지 않음')
+     * ```
+     *
+     * @param {string} key - 키
+     * @returns {Promise<boolean>} 삭제 성공 여부
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * 모든 값 삭제
+     *
+     * @description
+     * 현재 접두사로 시작하는 모든 키의 값을 LocalStorage에서 삭제합니다.
+     * 성능 최적화를 위해 모든 키를 한 번에 가져와서 필터링합니다.
+     *
+     * @example
+     * ```typescript
+     * await storage.clear()
+     * console.log('모든 데이터 삭제 완료')
+     * ```
+     *
+     * @returns {Promise<void>}
+     */
+    clear(): Promise<void>;
+    /**
+     * 키 존재 여부 확인
+     *
+     * @description
+     * LocalStorage에 특정 키가 존재하는지 확인합니다.
+     *
+     * @example
+     * ```typescript
+     * if (await storage.has('user_preferences')) {
+     *   const prefs = await storage.get('user_preferences')
+     * }
+     * ```
+     *
+     * @param {string} key - 키
+     * @returns {Promise<boolean>} 존재 여부
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 저장된 항목 수
+     *
+     * @description
+     * 현재 접두사로 저장된 모든 항목의 개수를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const count = await storage.size()
+     * console.log(`저장된 항목 수: ${count}`)
+     * ```
+     *
+     * @returns {Promise<number>} 항목 수
+     */
+    size(): Promise<number>;
+    /**
+     * 모든 키 반환
+     *
+     * @description
+     * 현재 접두사로 저장된 모든 키를 배열로 반환합니다.
+     * 접두사는 제거된 원본 키를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const allKeys = await storage.keys()
+     * for (const key of allKeys) {
+     *   console.log(`Key: ${key}`)
+     * }
+     * ```
+     *
+     * @returns {Promise<string[]>} 키 배열
+     */
+    keys(): Promise<string[]>;
+    /**
+     * 오래된 항목 정리 (LRU 방식)
+     *
+     * @description
+     * LocalStorage 용량이 부족할 때 가장 오래된 항목들을 삭제합니다.
+     * 타임스탬프를 기준으로 오래된 순으로 정렬하여 하위 20%를 삭제합니다.
+     *
+     * @private
+     * @returns {Promise<void>}
+     */
+    private clearOldItems;
+    /**
+     * 타임스탬프와 함께 저장 (LRU 지원)
+     *
+     * @deprecated set 메서드가 이미 타임스탬프를 포함합니다
+     * @param {string} key - 키
+     * @param {T} value - 저장할 값
+     * @returns {Promise<void>}
+     */
+    setWithTimestamp<T = unknown>(key: string, value: T): Promise<void>;
+}
+
+/**
+ * 웹 성능 측정 및 추적
+ */
+declare class WebPerformanceTracker {
+    private observer?;
+    private marks;
+    /**
+     * 성능 추적 시작
+     */
+    startTracking(): void;
+    /**
+     * 성능 추적 중지
+     */
+    stopTracking(): void;
+    /**
+     * Performance API 지원 여부 확인
+     */
+    private isSupported;
+    /**
+     * Long Task 감지
+     */
+    private observeLongTasks;
+    /**
+     * Layout Shift 감지
+     */
+    private observeLayoutShifts;
+    /**
+     * Largest Contentful Paint 감지
+     */
+    private observeLCP;
+    /**
+     * First Input Delay 감지
+     */
+    private observeFID;
+    /**
+     * 커스텀 성능 마크 시작
+     * @param name - 마크 이름
+     */
+    mark(name: string): void;
+    /**
+     * 커스텀 성능 측정
+     * @param name - 마크 이름
+     * @returns 측정된 시간 (ms)
+     */
+    measure(name: string): number | null;
+    /**
+     * 페이지 로드 메트릭 가져오기
+     */
+    getLoadMetrics(): Record<string, number>;
+    /**
+     * 리소스 타이밍 데이터 가져오기
+     */
+    getResourceTimings(): Array<{
+        name: string;
+        type: string;
+        duration: number;
+        size: number;
+    }>;
+}
+/**
+ * 함수 실행 시간 측정 데코레이터
+ */
+declare function measurePerformance(target: unknown, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+ * 디바운스 유틸리티
+ * @param func - 디바운스할 함수
+ * @param wait - 대기 시간 (ms)
+ * @returns 디바운스된 함수
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * 쓰로틀 유틸리티
+ * @param func - 쓰로틀할 함수
+ * @param limit - 제한 시간 (ms)
+ * @returns 쓰로틀된 함수
+ */
+declare function throttle<T extends (...args: unknown[]) => unknown>(func: T, limit: number): (...args: Parameters<T>) => void;
+
+/**
+ * Vircle Web SDK 전용 에러 클래스
+ *
+ * @description
+ * Vircle Web SDK에서 발생하는 모든 에러의 기본 클래스입니다.
+ * 에러 코드와 상세 정보를 포함하여 디버깅을 용이하게 합니다.
+ *
+ * @example
+ * ```typescript
+ * throw new VircleWebError(
+ *   'API 키가 유효하지 않습니다',
+ *   'INVALID_API_KEY',
+ *   { apiKey: 'xxx...xxx' }
+ * )
+ * ```
+ */
+declare class VircleWebError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/**
+ * 설정 관련 에러
+ *
+ * @description
+ * SDK 설정에 문제가 있을 때 발생하는 에러입니다.
+ * API 키 누락, 잘못된 설정 값 등의 경우에 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!config.apiKey) {
+ *   throw new VircleConfigError('API 키가 필수입니다')
+ * }
+ * ```
+ */
+declare class VircleConfigError extends VircleWebError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * 초기화 관련 에러
+ *
+ * @description
+ * SDK 초기화 과정에서 발생하는 에러입니다.
+ * 브라우저 호환성, 필수 API 지원 여부 등을 확인할 때 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!window.Promise) {
+ *   throw new VircleInitializationError(
+ *     'Promise API를 지원하지 않는 브라우저입니다'
+ *   )
+ * }
+ * ```
+ */
+declare class VircleInitializationError extends VircleWebError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * 스토리지 관련 에러
+ *
+ * @description
+ * LocalStorage 접근 실패, 용량 초과, 직렬화 오류 등
+ * 스토리지 작업 중 발생하는 에러입니다.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   localStorage.setItem(key, value)
+ * } catch (error) {
+ *   throw new VircleStorageError(
+ *     'LocalStorage 용량 초과',
+ *     { key, size: value.length }
+ *   )
+ * }
+ * ```
+ */
+declare class VircleStorageError extends VircleWebError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * 브라우저 호환성 에러
+ *
+ * @description
+ * 현재 브라우저가 SDK에 필요한 기능을 지원하지 않을 때 발생하는 에러입니다.
+ * 필수 API 또는 기능이 누락된 경우에 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!window.fetch) {
+ *   throw new VircleBrowserCompatibilityError(
+ *     'Fetch API를 지원하지 않는 브라우저입니다',
+ *     { userAgent: navigator.userAgent }
+ *   )
+ * }
+ * ```
+ */
+declare class VircleBrowserCompatibilityError extends VircleWebError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+export { LocalStorageAdapter, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebPerformanceTracker, debounce, VircleWeb as default, measurePerformance, throttle };
+export type { VircleWebConfig, VircleWebOptions };