@adstage/web-sdk 1.3.3 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "1.3.3",
-  "description": "AdStage Web SDK for displaying advertisements",
+  "version": "1.4.0",
+  "description": "AdStage Web SDK for displaying advertisements with auto DOM-ready detection",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/constants/endpoints.ts

@@ -0,0 +1,93 @@
+/**
+ * AdStage SDK 엔드포인트 상수 관리
+ * 모든 API URL을 중앙에서 관리
+ */
+
+/**
+ * 환경별 API 엔드포인트 (읽기 전용)
+ */
+export const API_ENDPOINTS = {
+  /** 프로덕션 환경 */
+  production: 'https://api.adstage.io',
+  
+  /** 베타 환경 (기본값) */
+  beta: 'https://beta-api.adstage.app'
+} as const;
+
+/**
+ * 기본 엔드포인트 (베타 환경)
+ */
+export const DEFAULT_API_ENDPOINT = API_ENDPOINTS.beta;
+
+/**
+ * API 경로 상수
+ */
+export const API_PATHS = {
+  /** 광고 관련 */
+  advertisements: {
+    list: '/advertisements/list',
+    events: '/advertisements/events'
+  },
+  
+  /** 이벤트 관련 */
+  events: {
+    track: '/events/track',
+    batch: '/events/batch'
+  }
+} as const;
+
+/**
+ * 완전한 API URL 생성 헬퍼
+ */
+export class EndpointBuilder {
+  private baseUrl: string;
+
+  constructor(baseUrl?: string) {
+    // 기본값은 베타 환경 사용
+    this.baseUrl = baseUrl || API_ENDPOINTS.beta;
+  }
+
+  /**
+   * 기본 URL 변경
+   */
+  setBaseUrl(url: string): void {
+    this.baseUrl = url;
+    console.log('🔄 API endpoint changed:', url);
+  }
+
+  /**
+   * 기본 URL 반환
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  /**
+   * 광고 엔드포인트
+   */
+  advertisements = {
+    list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
+    events: (adId: string, eventType: string) => 
+      `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
+  };
+
+  /**
+   * 이벤트 엔드포인트
+   */
+  events = {
+    track: () => `${this.baseUrl}${API_PATHS.events.track}`,
+    batch: () => `${this.baseUrl}${API_PATHS.events.batch}`
+  };
+
+  /**
+   * 커스텀 경로 생성
+   */
+  custom(path: string): string {
+    return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+  }
+}
+
+/**
+ * 전역 엔드포인트 빌더 인스턴스 (기본: 베타 환경)
+ */
+export const endpoints = new EndpointBuilder();

package/src/core/AdStage.ts

@@ -0,0 +1,128 @@
+/**
+ * AdStage SDK - 메인 네임스페이스 클래스
+ * v2.0.0 - 확장 가능한 모듈 아키텍처
+ */
+
+import { AdStageConfig, ModuleName } from '../types/config';
+import { AdsModule } from '../modules/ads/AdsModule';
+import { ConfigModule } from '../modules/config/ConfigModule';
+import { EventsModule } from '../modules/events/EventsModule';
+
+export class AdStage {
+  private static instance: AdStage;
+  private _isInitialized = false;
+  private _config: AdStageConfig | null = null;
+  
+  // 모듈 인스턴스들
+  public readonly ads: AdsModule;
+  public readonly config: ConfigModule;
+  public readonly events: EventsModule;
+
+  private constructor() {
+    // 모듈 초기화 (ads, config는 완전 구현, events는 기본 구조)
+    this.config = new ConfigModule();
+    this.ads = new AdsModule();
+    this.events = new EventsModule();
+  }
+
+  /**
+   * AdStage SDK 초기화 (동기)
+   */
+  public static init(config: AdStageConfig): void {
+    if (!AdStage.instance) {
+      AdStage.instance = new AdStage();
+    }
+
+    const instance = AdStage.instance;
+    
+    // 설정 검증
+    if (!config.apiKey) {
+      throw new Error('API key is required for AdStage initialization');
+    }
+
+    // 설정 저장 (서버 검증 없음)
+    instance._config = {
+      timeout: 30000,
+      debug: false,
+      modules: ['ads', 'events', 'config'],
+      validateOnInit: false,
+      fallbackMode: true,
+      offlineMode: false,
+      productionMode: false,
+      ...config
+    };
+
+    // 모듈 동기 초기화
+    const enabledModules = instance._config.modules || ['ads', 'events', 'config'];
+    
+    for (const moduleName of enabledModules) {
+      const module = instance[moduleName as keyof AdStage] as any;
+      if (module && typeof module.init === 'function') {
+        module.init(instance._config);
+      }
+    }
+
+    instance._isInitialized = true;
+
+    if (config.debug) {
+      console.log('🚀 AdStage SDK initialized (sync mode)', {
+        version: '2.0.0',
+        modules: enabledModules,
+        apiKey: config.apiKey.substring(0, 8) + '...',
+        mode: config.productionMode ? 'production' : 'development'
+      });
+    }
+  }
+
+  /**
+   * SDK 초기화 상태 확인
+   */
+  public static isReady(): boolean {
+    return AdStage.instance?._isInitialized || false;
+  }
+
+  /**
+   * 현재 설정 반환
+   */
+  public static getConfig(): AdStageConfig | null {
+    return AdStage.instance?._config || null;
+  }
+
+  /**
+   * SDK 인스턴스 반환 (공개 메소드로 변경)
+   */
+  public static getInstance(): AdStage {
+    if (!AdStage.instance) {
+      throw new Error('AdStage not initialized. Call AdStage.init() first.');
+    }
+    return AdStage.instance;
+  }
+
+  /**
+   * 편의성을 위한 정적 모듈 접근자들
+   */
+  public static get ads() {
+    return AdStage.getInstance().ads;
+  }
+
+  public static get events() {
+    return AdStage.getInstance().events;
+  }
+
+  public static get config() {
+    return AdStage.getInstance().config;
+  }
+
+  /**
+   * SDK 리셋 (테스트용)
+   */
+  public static reset(): void {
+    if (AdStage.instance) {
+      AdStage.instance._isInitialized = false;
+      AdStage.instance._config = null;
+    }
+  }
+}
+
+// 전역 네임스페이스로 내보내기
+export default AdStage;

package/src/index.ts

@@ -1,420 +1,21 @@
-import { AdType, AdEventType } from './types/advertisement';
-import type { AdSlot, Advertisement } from './types/advertisement';
-import { AdRendererFactory } from './renderers';
-import { SliderManager } from './managers/slider-manager';
-import { FadeSliderManager } from './managers/fade-slider-manager';
-import { ImpressionTracker } from './managers/impression-tracker';
-import { EventTracker } from './managers/event-tracker';
-import { DeviceInfoCollector } from './managers/device-info-collector';
-import { SDKUtils } from './utils/sdk-utils';
-import { DOMUtils } from './utils/dom-utils';
-
 /**
- * AdStage SDK 설정
+ * AdStage Web SDK
+ * 네임스페이스 아키텍처 기반 SDK
  */
-export interface AdStageConfig {
-  apiKey: string;
-  debug?: boolean;
-}
-
-/**
- * AdStage SDK 메인 클래스
- * - 간단한 API Key 기반 초기화
- * - 광고 슬롯 자동 관리
- * - 이벤트 자동 추적
- */
-export class AdStageSDK {
-  private static instance: AdStageSDK | null = null;
-  
-  private config: AdStageConfig;
-  private baseUrl = 'https://beta-api.adstage.app';
-  private slots = new Map<string, AdSlot>();
-  private initialized = false;
-  private eventTracker: EventTracker;
-  
-  constructor(config: AdStageConfig) {
-    this.config = {
-      debug: false,
-      ...config,
-    };
-    
-    this.eventTracker = new EventTracker(
-      this.baseUrl,
-      this.config.apiKey,
-      this.config.debug || false,
-      this.slots
-    );
-  }
-  
-  /**
-   * SDK 초기화 및 인스턴스 반환
-   */
-  static init(config: AdStageConfig): AdStageSDK {
-    if (!AdStageSDK.instance) {
-      AdStageSDK.instance = new AdStageSDK(config);
-    }
-    
-    return AdStageSDK.instance;
-  }
-  
-  /**
-   * SDK 인스턴스 반환 (이미 초기화된 경우)
-   */
-  static getInstance(): AdStageSDK {
-    if (!AdStageSDK.instance) {
-      throw new Error('AdStageSDK must be initialized first. Call AdStageSDK.init(config)');
-    }
-    
-    return AdStageSDK.instance;
-  }
-  
-  /**
-   * 광고 슬롯 생성 및 로드
-   */
-  async createSlot(
-    id: string,
-    containerId: string,
-    adType: AdType = AdType.BANNER,
-    options?: {
-      width?: number | string;  // 숫자(px) 또는 문자열(%, px 등) 지원
-      height?: number | string; // 숫자(px) 또는 문자열(%, px 등) 지원
-      language?: string;
-      deviceType?: string;
-      country?: string;
-      autoSlideInterval?: number; // 자동 슬라이드 간격 (초), 기본값: 3초
-      sliderEffect?: 'slide' | 'fade'; // 슬라이더 효과 선택 (기본값: slide)
-    }
-  ): Promise<void> {
-    const container = DOMUtils.safeGetElementById(containerId);
-    if (!container) {
-      if (DOMUtils.canUseDOM()) {
-        console.error(`Container with ID "${containerId}" not found`);
-      }
-      return;
-    }
-
-    const slot: AdSlot = {
-      id,
-      containerId,
-      adType,
-      width: options?.width || 0,  // 문자열도 지원
-      height: options?.height || 0, // 문자열도 지원
-      isLoaded: false,
-      isVisible: false,
-      refreshRate: 0,
-      lazyLoad: false,
-      targeting: {},
-      load: async () => { await this.loadSlot(slot, options); return null; },
-      render: (ad: Advertisement) => this.renderSlot(slot, ad),
-      refresh: () => this.refreshSlot(slot.id),
-      destroy: () => this.destroySlot(slot.id),
-    };
-
-    this.slots.set(id, slot);
-    await this.loadSlot(slot, options);
-  }
-
-  /**
-   * 광고 슬롯 로드
-   */
-  private async loadSlot(slot: AdSlot, options?: any): Promise<void> {
-    try {
-      const queryParams = new URLSearchParams({
-        adType: slot.adType,
-        status: 'ACTIVE', // ACTIVE 상태인 광고만 조회
-        ...(options?.language && { language: options.language }),
-        ...(options?.deviceType && { deviceType: options.deviceType }),
-        ...(options?.country && { country: options.country }),
-      });
-
-      const requestUrl = `${this.baseUrl}/advertisements/list?${queryParams}`;
-      
-      if (this.config.debug) {
-        console.log(`🌐 광고 API 요청 시작:`, {
-          url: requestUrl,
-          apiKey: this.config.apiKey.substring(0, 10) + '...',
-          slot: slot.id
-        });
-      }
-
-      const response = await fetch(requestUrl, {
-        headers: {
-          'x-api-key': this.config.apiKey,
-          'Content-Type': 'application/json',
-        },
-      });
-
-      if (this.config.debug) {
-        console.log(`📡 API 응답 상태:`, {
-          status: response.status,
-          statusText: response.statusText,
-          ok: response.ok
-        });
-      }
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      const data = await response.json();
-      
-      if (this.config.debug) {
-        console.log(`📊 API 응답 데이터:`, {
-          data,
-          advertisementsCount: data.advertisements ? data.advertisements.length : 0
-        });
-      }
-      
-      const advertisements = data.advertisements || [];
-
-      if (advertisements.length > 0) {
-        if (this.config.debug) {
-          console.log(`✅ ${advertisements.length}개 광고 발견:`, advertisements);
-        }
-        
-        // 여러 광고가 있을 경우 슬라이드로 렌더링
-        this.renderSlotWithSlider(slot, advertisements, options);
-        
-        // 첫 번째 광고에 대해서만 노출 이벤트 추적
-        await this.eventTracker.trackEvent(advertisements[0]._id, slot.id, AdEventType.IMPRESSION);
-      } else {
-        console.warn(`⚠️ 슬롯 ${slot.id}에 사용 가능한 광고가 없습니다. API 응답:`, data);
-      }
-    } catch (error) {
-      console.error(`❌ 슬롯 ${slot.id} 로드 실패:`, error);
-    }
-  }
-
-  /**
-   * 광고 슬롯 렌더링 (슬라이더 포함)
-   */
-  private renderSlotWithSlider(slot: AdSlot, advertisements: Advertisement[], options?: any): void {
-    const container = DOMUtils.safeGetElementById(slot.containerId);
-    if (!container) {
-      console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
-      return;
-    }
-
-    if (this.config.debug) {
-      console.log(`🎨 광고 렌더링 시작:`, {
-        slotId: slot.id,
-        containerId: slot.containerId,
-        advertisementCount: advertisements.length,
-        container: container
-      });
-    }
-
-    if (advertisements.length === 1) {
-      // 광고가 하나뿐이면 기본 렌더링
-      this.renderSlot(slot, advertisements[0]);
-      return;
-    }
-
-    // 슬라이더 효과 결정 (옵션으로 지정하거나 텍스트 광고인 경우 fade 기본값)
-    const isAllTextAds = advertisements.every(ad => ad.adType === AdType.TEXT);
-    const useFadeEffect = options?.sliderEffect === 'fade' || 
-                         (options?.sliderEffect !== 'slide' && isAllTextAds);
-    
-    let sliderContainer: HTMLElement;
-    
-    if (useFadeEffect) {
-      // 페이드 슬라이더 사용
-      sliderContainer = FadeSliderManager.createFadeSliderContainer(
-        slot, 
-        advertisements, 
-        options,
-        (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
-      );
-    } else {
-      // 기본 슬라이더 사용
-      sliderContainer = SliderManager.createSliderContainer(
-        slot, 
-        advertisements, 
-        options,
-        (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
-      );
-    }
-    
-    container.innerHTML = '';
-    container.appendChild(sliderContainer);
-    slot.isLoaded = true;
-
-    if (this.config.debug) {
-      const sliderType = useFadeEffect ? 'fade slider' : 'slider';
-      console.log(`✅ ${advertisements.length}개 광고를 ${sliderType}로 렌더링 완료:`, {
-        slotId: slot.id,
-        container: container,
-        sliderContainer: sliderContainer
-      });
-    }
-  }
-
-  /**
-   * 광고 슬롯 렌더링 (단일 광고용)
-   */
-  private renderSlot(slot: AdSlot, ad: Advertisement): void {
-    const container = DOMUtils.safeGetElementById(slot.containerId);
-    if (!container) {
-      console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
-      return;
-    }
-
-    if (this.config.debug) {
-      console.log(`🎨 단일 광고 렌더링 시작:`, {
-        slotId: slot.id,
-        containerId: slot.containerId,
-        ad: ad,
-        container: container
-      });
-    }
-
-    // 팩토리를 사용해서 적절한 렌더러로 광고 생성
-    const adElement = AdRendererFactory.render(
-      ad, 
-      slot, 
-      (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
-    );
-
-    if (this.config.debug) {
-      console.log(`🔧 광고 요소 생성됨:`, {
-        adElement: adElement,
-        tagName: adElement.tagName,
-        innerHTML: adElement.innerHTML.substring(0, 200) + '...'
-      });
-    }
-
-    container.innerHTML = '';
-    container.appendChild(adElement);
-    slot.isLoaded = true;
-
-    if (this.config.debug) {
-      console.log(`✅ 단일 광고 렌더링 완료:`, {
-        slotId: slot.id,
-        ad: ad,
-        containerContent: container.innerHTML.substring(0, 200) + '...'
-      });
-    }
-  }
-
-  /**
-   * 광고 슬롯 새로고침
-   */
-  async refreshSlot(slotId: string): Promise<void> {
-    const slot = this.slots.get(slotId);
-    if (slot) {
-      await this.loadSlot(slot);
-    }
-  }
-
-  /**
-   * 광고 슬롯 제거
-   */
-  destroySlot(slotId: string): void {
-    const slot = this.slots.get(slotId);
-    if (slot) {
-      const container = DOMUtils.safeGetElementById(slot.containerId);
-      if (container) {
-        DOMUtils.safeSetInnerHTML(container, '');
-      }
-      this.slots.delete(slotId);
-    }
-  }
-
-  /**
-   * 자동 슬롯 검색 및 로드 (분리된 SDKUtils 사용)
-   */
-  async autoLoadSlots(): Promise<void> {
-    const elements = SDKUtils.findAutoSlotElements();
-
-    for (const element of elements) {
-      const slotInfo = SDKUtils.extractSlotInfo(element);
-      
-      if (!slotInfo.slotId || this.slots.has(slotInfo.slotId)) continue;
-      
-      const adType = SDKUtils.parseAdType(slotInfo.adType, AdType);
-
-      await this.createSlot(slotInfo.slotId, element.id || slotInfo.slotId, adType, {
-        width: slotInfo.width,
-        height: slotInfo.height,
-        language: slotInfo.language,
-        deviceType: slotInfo.deviceType,
-        country: slotInfo.country,
-        sliderEffect: slotInfo.sliderEffect as 'slide' | 'fade' | undefined,
-      });
-    }
-  }
-
-  /**
-   * SDK 정리
-   */
-  destroy(): void {
-    this.slots.clear();
-    ImpressionTracker.clear(); // 노출 추적 데이터도 정리
-    this.initialized = false;
-    AdStageSDK.instance = null;
-  }
-
-  /**
-   * 디바이스 ID 가져오기
-   */
-  getDeviceId(): string {
-    return DeviceInfoCollector.generateDeviceId();
-  }
-
-  /**
-   * 세션 ID 가져오기
-   */
-  getSessionId(): string {
-    return DeviceInfoCollector.generateSessionId();
-  }
-
-  /**
-   * 현재 로드된 슬롯 수 가져오기
-   */
-  getLoadedSlotCount(): number {
-    return this.slots.size;
-  }
-
-  /**
-   * 모든 슬롯 정보 가져오기
-   */
-  getAllSlots(): Map<string, AdSlot> {
-    return new Map(this.slots);
-  }
-}
-
-async function autoInit() {
-  if (DOMUtils.isBrowser() && (window as any).adstageConfig) {
-    try {
-      const sdk = AdStageSDK.init((window as any).adstageConfig);
-      await sdk.autoLoadSlots();
-    } catch (error) {
-      console.error('Failed to auto-initialize AdStageSDK:', error);
-    }
-  }
-}
 
-// 브라우저 환경에서 자동 초기화
-if (DOMUtils.isBrowser()) {
-  // 타입 단언을 사용하여 window 객체에 할당
-  (window as any).AdStageSDK = AdStageSDK;
-  
-  // DOM 로드 후 자동 초기화
-  if (DOMUtils.isDOMReady()) {
-    autoInit();
-  } else {
-    DOMUtils.waitForDOM().then(autoInit);
-  }
-}
+// 메인 네임스페이스 클래스
+export { default as AdStage } from './core/AdStage';
 
-export default AdStageSDK;
+// 설정 및 타입
+export type { AdStageConfig, ModuleName, BaseModule, ApiResponse, OrganizationInfo } from './types/config';
 
-// Core SDK exports
-export { AdType, AdEventType };
-export type { AdSlot, Advertisement };
+// 모듈별 타입
+export type { AdOptions } from './modules/ads/AdsModule';
+export type { EventProperties, PageData } from './modules/events/EventsModule';
 
-// Standalone API (추천 사용법)
-export * from './utils/sdk-standalone';
+// 광고 관련 타입
+export type { AdType, AdEventType, Advertisement, AdSlot } from './types/advertisement';
 
-// React exports (React가 있을 때만 사용 - 레거시)
-// export * from './react';
+// 버전 정보
+export const SDK_VERSION = '2.0.0';
+export const SUPPORTED_MODULES = ['ads', 'events', 'config'] as const;

package/src/managers/{slider-manager.ts → carousel-slider-manager.ts}

@@ -3,18 +3,19 @@ import type { AdSlot, Advertisement } from '../types/advertisement';
 import { AdRendererFactory } from '../renderers';
 
 /**
- * 슬라이더 관리 클래스
- * - 다중 광고 슬라이더 생성 및 관리
- * - 무한 루프 슬라이더 지원
+ * 캐러셀 슬라이더 관리 클래스
+ * - 배너/비디오 광고용 가로 슬라이드 (횡 스크롤)
+ * - 무한 루프 캐러셀 지원
  * - 터치 제스처 및 자동 슬라이드 기능
+ * - 도트 인디케이터 포함
  */
-export class SliderManager {
+export class CarouselSliderManager {
   /**
-   * 슬라이더 컨테이너 생성
+   * Create carousel slider container with dot indicators and navigation
    */
   static createSliderContainer(
     slot: AdSlot,
-    advertisements: Advertisement[],
+    advertisements: any[],
     options: any,
     trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void
   ): HTMLElement {
@@ -175,7 +176,7 @@ export class SliderManager {
     const isAllTextAds = advertisements.every(ad => ad.adType === AdType.TEXT);
     
     // 무채색 도트 인디케이터 생성 (원본 광고 수만큼) - 텍스트 광고가 아닐 때만
-    const dotContainer = isAllTextAds ? null : SliderManager.createMinimalDotIndicator(advertisements.length);
+    const dotContainer = isAllTextAds ? null : this.createMinimalDotIndicator(advertisements.length);
     
     // 슬라이더 상태 관리
     let currentSlide = 0;
@@ -261,7 +262,7 @@ export class SliderManager {
     });
 
     // 터치 제스처 지원 수정 (무한 루프 지원)
-    SliderManager.addTouchSupport(slideContainer, moveToSlide, () => currentSlide, totalSlides, handleInfiniteLoop);
+    this.addTouchSupport(slideContainer, moveToSlide, () => currentSlide, totalSlides, handleInfiniteLoop);
 
     // 요소들 조립 (화살표 제거, 도트는 텍스트 광고가 아닐 때만 추가)
     sliderWrapper.appendChild(slideContainer);