@adstage/web-sdk 1.3.4 → 2.0.0

package/dist/index.d.ts

@@ -1,3 +1,60 @@
+/**
+ * AdStage SDK 모듈 타입
+ */
+type ModuleName = 'ads' | 'events' | 'config';
+/**
+ * AdStage SDK 초기화 설정
+ */
+interface AdStageConfig {
+    /** API 키 (조직 정보 자동 추출) */
+    apiKey: string;
+    /** 디버그 모드 활성화 */
+    debug?: boolean;
+    /** API 기본 URL (선택사항, 기본값: 환경 자동 감지) */
+    baseUrl?: string;
+    /** 로드할 모듈 선택 (기본값: 모든 모듈) */
+    modules?: ModuleName[];
+    /** 요청 타임아웃 (ms) */
+    timeout?: number;
+    /** 초기화시 API 키 검증 여부 (기본값: false) */
+    validateOnInit?: boolean;
+    /** 네트워크 오류시 fallback 모드 사용 (기본값: true) */
+    fallbackMode?: boolean;
+    /** 오프라인 모드 (기본값: false) */
+    offlineMode?: boolean;
+    /** 프로덕션 모드 (엄격한 검증, 기본값: false) */
+    productionMode?: boolean;
+}
+/**
+ * 모듈 기본 인터페이스
+ */
+interface BaseModule {
+    /** 모듈 초기화 (동기) */
+    init(config: AdStageConfig): void;
+    /** 모듈 준비 상태 확인 */
+    isReady(): boolean;
+    /** 모듈 설정 반환 */
+    getConfig(): any;
+}
+/**
+ * API 응답 기본 타입
+ */
+interface ApiResponse<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+/**
+ * 조직 정보
+ */
+interface OrganizationInfo {
+    id: string;
+    name: string;
+    slug: string;
+    settings: Record<string, any>;
+}
+
 declare enum AdType {
     BANNER = "BANNER",
     POPUP = "POPUP",
@@ -153,141 +210,273 @@ interface AdSlot {
 }
 
 /**
- * AdStage SDK Standalone API
- * 간단하고 직관적인 사용을 위한 통합 API
+ * AdStage SDK - Ads 모듈
+ * 광고 관리 및 렌더링 기능
  */
-interface SimpleAdStageConfig {
-    apiKey: string;
-    debug?: boolean;
-    baseUrl?: string;
-}
-/**
- * SDK 초기화 (한 번만 호출)
- */
-declare function initAdStage(config: SimpleAdStageConfig): Promise<void>;
-/**
- * 배너 광고 생성 (가장 간단한 API)
- */
-declare function createBanner(containerId: string, options?: {
+
+interface AdOptions {
     width?: string | number;
-    height?: string | number;
+    height?: number;
     autoSlide?: boolean;
     slideInterval?: number;
-}): Promise<void>;
-/**
- * 텍스트 광고 생성
- */
-declare function createTextAd(containerId: string, options?: {
     maxLines?: number;
-    style?: 'minimal' | 'card' | 'banner';
-}): Promise<void>;
-/**
- * 비디오 광고 생성
- */
-declare function createVideoAd(containerId: string, options?: {
-    width?: string | number;
-    height?: string | number;
+    style?: string;
     autoplay?: boolean;
     muted?: boolean;
-}): Promise<void>;
-/**
- * SDK 상태 확인
- */
-declare function isAdStageReady(): boolean;
-/**
- * SDK 인스턴스 가져오기 (고급 사용자용)
- */
-declare function getAdStageInstance(): any;
-/**
- * SDK 초기화 해제 (필요시)
- */
-declare function destroyAdStage(): void;
-
-/**
- * AdStage SDK 설정
- */
-interface AdStageConfig {
-    apiKey: string;
-    debug?: boolean;
+    onClick?: (adData: any) => void;
 }
-/**
- * AdStage SDK 메인 클래스
- * - 간단한 API Key 기반 초기화
- * - 광고 슬롯 자동 관리
- * - 이벤트 자동 추적
- */
-declare class AdStageSDK {
-    private static instance;
-    private config;
-    private baseUrl;
+declare class AdsModule implements BaseModule {
+    private _isReady;
+    private _config;
     private slots;
-    private initialized;
     private eventTracker;
-    constructor(config: AdStageConfig);
     /**
-     * SDK 초기화 및 인스턴스 반환
+     * Ads 모듈 초기화 (동기)
+     */
+    init(config: AdStageConfig): void;
+    /**
+     * 모듈 준비 상태 확인
      */
-    static init(config: AdStageConfig): AdStageSDK;
+    isReady(): boolean;
     /**
-     * SDK 인스턴스 반환 (이미 초기화된 경우)
+     * 모듈 설정 반환
      */
-    static getInstance(): AdStageSDK;
+    getConfig(): AdStageConfig | null;
     /**
-     * 광고 슬롯 생성 및 로드
+     * 배너 광고 생성 (동기)
      */
-    createSlot(id: string, containerId: string, adType?: AdType, options?: {
-        width?: number | string;
-        height?: number | string;
-        language?: string;
-        deviceType?: string;
-        country?: string;
-        autoSlideInterval?: number;
-        sliderEffect?: 'slide' | 'fade';
-    }): Promise<void>;
+    banner(containerId: string, options?: AdOptions): string;
     /**
-     * 광고 슬롯 로드
+     * 텍스트 광고 생성 (동기)
      */
-    private loadSlot;
+    text(containerId: string, options?: AdOptions): string;
     /**
-     * 광고 슬롯 렌더링 (슬라이더 포함)
+     * 비디오 광고 생성 (동기)
      */
-    private renderSlotWithSlider;
+    video(containerId: string, options?: AdOptions): string;
     /**
-     * 광고 슬롯 렌더링 (단일 광고용)
+     * 네이티브 광고 생성 (동기)
      */
-    private renderSlot;
+    native(containerId: string, options?: AdOptions): string;
+    /**
+     * 전면 광고 생성 (동기)
+     */
+    interstitial(containerId: string, options?: AdOptions): string;
+    /**
+     * 광고 새로고침
+     */
+    refresh(slotId: string): void;
+    /**
+     * 광고 제거
+     */
+    destroy(slotId: string): void;
+    /**
+     * 모든 광고 슬롯 반환
+     */
+    getAllSlots(): AdSlot[];
+    /**
+     * 특정 광고 슬롯 반환
+     */
+    getSlotById(slotId: string): AdSlot | null;
+    /**
+     * 광고 생성 내부 메소드 (동기 + Lazy 로딩)
+     */
+    private createAd;
+    /**
+     * 즉시 광고 슬롯 생성 (placeholder)
+     */
+    private createAdSlot;
+    /**
+     * 백그라운드에서 광고 콘텐츠 로드
+     */
+    private loadAdContentInBackground;
+    /**
+     * Fallback 광고 렌더링
+     */
+    private renderFallback;
+    /**
+     * 광고 데이터 가져오기
+     */
+    private fetchAdData;
+    /**
+     * 광고 슬라이더 렌더링 (여러 광고 또는 autoSlide 옵션)
+     */
+    private renderAdSlider;
+    /**
+     * 광고 렌더링 (단일 광고용)
+     */
+    private renderAd;
+    /**
+     * 광고 요소 렌더링 (기본 구현)
+     */
+    private renderAdElement;
     /**
      * 광고 슬롯 새로고침
      */
-    refreshSlot(slotId: string): Promise<void>;
+    private refreshAdSlot;
     /**
-     * 광고 슬롯 제거
+     * 모듈 준비 상태 확인
      */
-    destroySlot(slotId: string): void;
+    private ensureReady;
+}
+
+/**
+ * AdStage SDK - Config 모듈
+ * 설정 관리 및 API 키 검증
+ */
+
+declare class ConfigModule implements BaseModule {
+    private _isReady;
+    private _config;
+    private _organizationInfo;
     /**
-     * 자동 슬롯 검색 및 로드 (분리된 SDKUtils 사용)
+     * Config 모듈 초기화 (동기)
      */
-    autoLoadSlots(): Promise<void>;
+    init(config: AdStageConfig): void;
     /**
-     * SDK 정리
+     * 모듈 준비 상태 확인
      */
-    destroy(): void;
+    isReady(): boolean;
+    /**
+     * 현재 설정 반환
+     */
+    getConfig(): AdStageConfig | null;
+    /**
+     * 조직 정보 반환
+     */
+    getOrganizationInfo(): OrganizationInfo | null;
+    /**
+     * API 엔드포인트 반환
+     */
+    getApiEndpoint(): string;
+    /**
+     * 디버그 모드 여부 확인
+     */
+    isDebugMode(): boolean;
+    /**
+     * 활성화된 모듈 목록 반환
+     */
+    getEnabledModules(): string[];
+    /**
+     * 특정 모듈이 활성화되어 있는지 확인
+     */
+    isModuleEnabled(moduleName: string): boolean;
+    /**
+     * 설정 업데이트 (런타임)
+     */
+    updateConfig(updates: Partial<AdStageConfig>): void;
+    /**
+     * API 헤더 생성 (공통 유틸리티 사용)
+     */
+    getApiHeaders(): Record<string, string>;
+}
+
+/**
+ * AdStage SDK - Events 모듈 (기본 구조)
+ * 이벤트 추적 시스템 - Q1 2025 구현 예정
+ */
+
+interface EventProperties {
+    [key: string]: any;
+}
+interface PageData {
+    page?: string;
+    title?: string;
+    category?: string;
+    [key: string]: any;
+}
+declare class EventsModule implements BaseModule {
+    private _isReady;
+    private _config;
+    /**
+     * Events 모듈 초기화 (동기)
+     */
+    init(config: AdStageConfig): void;
+    /**
+     * 모듈 준비 상태 확인
+     */
+    isReady(): boolean;
+    /**
+     * 모듈 설정 반환
+     */
+    getConfig(): AdStageConfig | null;
+    /**
+     * 커스텀 이벤트 추적
+     * @example AdStage.events.track('page_view', { page: '/products' })
+     */
+    track(eventName: string, properties?: EventProperties): Promise<void>;
+    /**
+     * 페이지 뷰 이벤트
+     * @example AdStage.events.pageView({ page: '/home', title: 'Homepage' })
+     */
+    pageView(pageData?: PageData): Promise<void>;
+    /**
+     * 사용자 액션 이벤트
+     * @example AdStage.events.userAction('button_click', { button_id: 'cta' })
+     */
+    userAction(actionType: string, metadata?: EventProperties): Promise<void>;
+    /**
+     * 컨버전 이벤트
+     * @example AdStage.events.conversion({ type: 'purchase', value: 99.99 })
+     */
+    conversion(conversionData: EventProperties): Promise<void>;
+    batch: {
+        start: () => void;
+        add: (eventName: string, properties: EventProperties) => void;
+        flush: () => Promise<void>;
+    };
+    realtime: {
+        track: (eventName: string, properties: EventProperties) => Promise<void>;
+    };
+}
+
+/**
+ * AdStage SDK - 메인 네임스페이스 클래스
+ * v2.0.0 - 확장 가능한 모듈 아키텍처
+ */
+
+declare class AdStage {
+    private static instance;
+    private _isInitialized;
+    private _config;
+    readonly ads: AdsModule;
+    readonly config: ConfigModule;
+    readonly events: EventsModule;
+    private constructor();
     /**
-     * 디바이스 ID 가져오기
+     * AdStage SDK 초기화 (동기)
      */
-    getDeviceId(): string;
+    static init(config: AdStageConfig): void;
     /**
-     * 세션 ID 가져오기
+     * SDK 초기화 상태 확인
      */
-    getSessionId(): string;
+    static isReady(): boolean;
     /**
-     * 현재 로드된 슬롯 수 가져오기
+     * 현재 설정 반환
      */
-    getLoadedSlotCount(): number;
+    static getConfig(): AdStageConfig | null;
     /**
-     * 모든 슬롯 정보 가져오기
+     * SDK 인스턴스 반환 (공개 메소드로 변경)
      */
-    getAllSlots(): Map<string, AdSlot>;
+    static getInstance(): AdStage;
+    /**
+     * 편의성을 위한 정적 모듈 접근자들
+     */
+    static get ads(): AdsModule;
+    static get events(): EventsModule;
+    static get config(): ConfigModule;
+    /**
+     * SDK 리셋 (테스트용)
+     */
+    static reset(): void;
 }
 
-export { AdEventType, AdSlot, AdStageConfig, AdStageSDK, AdType, Advertisement, SimpleAdStageConfig, createBanner, createTextAd, createVideoAd, AdStageSDK as default, destroyAdStage, getAdStageInstance, initAdStage, isAdStageReady };
+/**
+ * AdStage Web SDK
+ * 네임스페이스 아키텍처 기반 SDK
+ */
+
+declare const SDK_VERSION = "2.0.0";
+declare const SUPPORTED_MODULES: readonly ["ads", "events", "config"];
+
+export { AdEventType, AdOptions, AdSlot, AdStage, AdStageConfig, AdType, Advertisement, ApiResponse, BaseModule, EventProperties, ModuleName, OrganizationInfo, PageData, SDK_VERSION, SUPPORTED_MODULES };