@adstage/web-sdk 1.3.4 → 2.0.0

package/src/modules/events/EventsModule.ts

@@ -0,0 +1,106 @@
+/**
+ * AdStage SDK - Events 모듈 (기본 구조)
+ * 이벤트 추적 시스템 - Q1 2025 구현 예정
+ */
+
+import { AdStageConfig, BaseModule } from '../../types/config';
+
+export interface EventProperties {
+  [key: string]: any;
+}
+
+export interface PageData {
+  page?: string;
+  title?: string;
+  category?: string;
+  [key: string]: any;
+}
+
+export class EventsModule implements BaseModule {
+  private _isReady = false;
+  private _config: AdStageConfig | null = null;
+
+  /**
+   * Events 모듈 초기화 (동기)
+   */
+  init(config: AdStageConfig): void {
+    this._config = config;
+    this._isReady = true;
+
+    if (config.debug) {
+      console.log('📊 Events module initialized (sync mode)');
+    }
+  }
+
+  /**
+   * 모듈 준비 상태 확인
+   */
+  isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * 모듈 설정 반환
+   */
+  getConfig(): AdStageConfig | null {
+    return this._config;
+  }
+
+  // === 향후 구현 예정 메소드들 ===
+
+  /**
+   * 커스텀 이벤트 추적
+   * @example AdStage.events.track('page_view', { page: '/products' })
+   */
+  async track(eventName: string, properties?: EventProperties): Promise<void> {
+    console.log('🚧 [TODO] Event tracking:', { eventName, properties });
+    // TODO: Q1 2025 구현 예정
+  }
+
+  /**
+   * 페이지 뷰 이벤트
+   * @example AdStage.events.pageView({ page: '/home', title: 'Homepage' })
+   */
+  async pageView(pageData?: PageData): Promise<void> {
+    console.log('🚧 [TODO] Page view tracking:', pageData);
+    // TODO: Q1 2025 구현 예정
+  }
+
+  /**
+   * 사용자 액션 이벤트
+   * @example AdStage.events.userAction('button_click', { button_id: 'cta' })
+   */
+  async userAction(actionType: string, metadata?: EventProperties): Promise<void> {
+    console.log('🚧 [TODO] User action tracking:', { actionType, metadata });
+    // TODO: Q1 2025 구현 예정
+  }
+
+  /**
+   * 컨버전 이벤트
+   * @example AdStage.events.conversion({ type: 'purchase', value: 99.99 })
+   */
+  async conversion(conversionData: EventProperties): Promise<void> {
+    console.log('🚧 [TODO] Conversion tracking:', conversionData);
+    // TODO: Q1 2025 구현 예정
+  }
+
+  // === 배치 처리 (향후 구현) ===
+  batch = {
+    start: () => {
+      console.log('🚧 [TODO] Batch events start');
+    },
+    add: (eventName: string, properties: EventProperties) => {
+      console.log('🚧 [TODO] Batch events add:', { eventName, properties });
+    },
+    flush: async () => {
+      console.log('🚧 [TODO] Batch events flush');
+    }
+  };
+
+  // === 실시간 이벤트 (향후 구현) ===
+  realtime = {
+    track: async (eventName: string, properties: EventProperties) => {
+      console.log('🚧 [TODO] Realtime event tracking:', { eventName, properties });
+    }
+  };
+}

package/src/types/config.ts

@@ -1,8 +1,79 @@
 // SDK 설정 타입 정의
 
-// 메인 SDK 설정
 /**
- * SDK 설정
+ * AdStage SDK 모듈 타입
+ */
+export type ModuleName = 'ads' | 'events' | 'config';
+
+/**
+ * AdStage SDK 초기화 설정
+ */
+export 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;
+}
+
+/**
+ * 모듈 기본 인터페이스
+ */
+export interface BaseModule {
+  /** 모듈 초기화 (동기) */
+  init(config: AdStageConfig): void;
+  
+  /** 모듈 준비 상태 확인 */
+  isReady(): boolean;
+  
+  /** 모듈 설정 반환 */
+  getConfig(): any;
+}
+
+/**
+ * API 응답 기본 타입
+ */
+export interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+}
+
+/**
+ * 조직 정보
+ */
+export interface OrganizationInfo {
+  id: string;
+  name: string;
+  slug: string;
+  settings: Record<string, any>;
+}
+
+// 메인 SDK 설정 (기존 호환성)
+/**
+ * SDK 설정 (레거시)
  */
 export interface SDKConfig {
   clientId: string;
@@ -128,7 +199,7 @@ export interface ConfigValidationResult {
 // 기본 설정 값들
 export const DEFAULT_CONFIG: Required<SDKConfig> = {
   clientId: '',
-  baseUrl: 'https://api.adstage.io',
+  baseUrl: 'https://beta-api.adstage.app', // 현재 개발 단계에서는 베타 URL 사용
   debug: false,
   batchSize: 10,
   retryCount: 3,

package/src/types/index.ts

@@ -1,6 +1,7 @@
 // 타입 정의 통합 인덱스
 export * from './advertisement';
 export * from './api';
-export * from './config';
+export type { AdStageConfig, ModuleName, BaseModule, OrganizationInfo } from './config';
+export type { ApiResponse as ConfigApiResponse } from './config';
 export * from './events';
 

package/src/utils/api-headers.ts

@@ -0,0 +1,52 @@
+/**
+ * AdStage SDK - API 헤더 유틸리티
+ * 공통 헤더 생성 로직
+ */
+
+export class ApiHeaders {
+  /**
+   * 표준 API 헤더 생성
+   */
+  static create(apiKey: string, options?: {
+    contentType?: string;
+    userAgent?: string;
+    currentUrl?: string;
+  }): Record<string, string> {
+    if (!apiKey) {
+      throw new Error('API key is required');
+    }
+
+    const headers: Record<string, string> = {
+      'x-api-key': apiKey,
+      'Content-Type': options?.contentType || 'application/json'
+    };
+
+    // User-Agent는 이벤트 추적에서 실제로 사용됨
+    if (typeof navigator !== 'undefined') {
+      headers['User-Agent'] = options?.userAgent || navigator.userAgent;
+    }
+
+    // X-Current-URL은 현재 서버에서 사용하지 않으므로 제거
+    // 필요시 이벤트 데이터 body에 포함
+
+    return headers;
+  }
+
+  /**
+   * 이벤트 추적용 헤더 생성
+   * User-Agent는 서버에서 실제로 사용됨
+   */
+  static createForEvents(apiKey: string, eventData?: Record<string, any>): Record<string, string> {
+    const baseHeaders = ApiHeaders.create(apiKey);
+    
+    // User-Agent 오버라이드 (서버에서 실제 사용)
+    if (eventData?.userAgent) {
+      baseHeaders['User-Agent'] = eventData.userAgent;
+    }
+
+    // 다른 정보들은 HTTP 헤더가 아닌 이벤트 데이터 body에 포함하는 것이 적절
+    // (currentUrl, referrer 등은 POST body로 전송)
+
+    return baseHeaders;
+  }
+}

package/src/utils/dom-utils.ts

@@ -286,7 +286,7 @@ export class DOMUtils {
           
 다음을 확인해보세요:
 1. HTML에 id="${id}" 요소가 있는지 확인
-2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+2. React 등에서 컴포넌트가 렌더링된 후 SDK 호출
 3. 철자가 정확한지 확인
 4. 중복된 ID가 없는지 확인
 

package/examples/README.md

@@ -1,33 +0,0 @@
-# API Key 설정 가이드
-
-이 예제들을 실행하기 전에 API 키를 설정해야 합니다.
-
-## React App 예제
-`sdk/examples/react-app/.env` 파일의 API 키를 설정하세요:
-```
-REACT_APP_ADSTAGE_API_KEY=your_api_key_here
-```
-
-## Next.js 예제  
-`sdk/examples/react-nextjs/.env` 파일의 API 키를 설정하세요:
-```
-NEXT_PUBLIC_ADSTAGE_API_KEY=your_api_key_here
-```
-
-## 실행 방법
-
-### React App 예제
-```bash
-cd sdk/examples/react-app
-pnpm install
-pnpm start
-```
-
-### Next.js 예제
-```bash
-cd sdk/examples/react-nextjs
-pnpm install
-pnpm dev
-```
-
-보안상 .env 파일은 Git에 커밋되지 않습니다. 실제 API 키는 AdStage 대시보드에서 발급받으세요.