@vircle/plugin-ecommerce-core 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# @vircle/plugin-ecommerce-core
+
+커머스 플랫폼 플러그인을 위한 기반 클래스와 유틸리티를 제공하는 패키지입니다. 플랫폼별 플러그인(Cafe24, Shopify 등)은 이 패키지를 확장하여 구현합니다.
+
+## 설치
+
+```bash
+pnpm add @vircle/plugin-ecommerce-core
+```
+
+## 구성 요소
+
+### BaseEcommercePlugin
+
+모든 커머스 플러그인의 추상 기반 클래스입니다. `VirclePlugin` 인터페이스를 구현하며, 다음 기능을 제공합니다:
+
+- 네트워크 요청 인터셉션 (fetch/XHR)
+- History API 기반 페이지 네비게이션 추적
+- 이벤트 중복 방지 (deduplication)
+- 플랫폼 메타데이터 자동 첨부
+- `globalProperties` — 모든 이벤트에 자동 병합되는 글로벌 프로퍼티 (크로스 도메인 어트리뷰션 등)
+
+```typescript
+import { BaseEcommercePlugin, EcommerceEvent, type NetworkPattern, type PlatformAdapter } from '@vircle/plugin-ecommerce-core';
+
+class MyPlatformPlugin extends BaseEcommercePlugin {
+    readonly name = 'my-platform';
+    readonly version = '1.0.0';
+    readonly description = 'My platform tracking plugin';
+
+    protected getNetworkPatterns(): NetworkPattern[] {
+        return [
+            { pattern: '/api/cart/add', method: 'POST', event: EcommerceEvent.PRODUCT_ADDED_TO_CART },
+        ];
+    }
+
+    protected createAdapter(): PlatformAdapter {
+        return new MyPlatformAdapter();
+    }
+
+    protected handleNetworkRequest(url: string, method: string, body?: any): void {
+        // 인터셉트된 네트워크 요청 처리
+    }
+}
+```
+
+### NetworkInterceptor
+
+`window.fetch`와 `XMLHttpRequest`를 패치하여 특정 URL 패턴에 매칭되는 네트워크 요청/응답을 인터셉트합니다.
+
+```typescript
+import { NetworkInterceptor, type NetworkPattern } from '@vircle/plugin-ecommerce-core';
+
+const patterns: NetworkPattern[] = [
+    { pattern: '/api/cart', method: 'POST', event: EcommerceEvent.PRODUCT_ADDED_TO_CART },
+    { pattern: /\/api\/order\/\d+/, event: EcommerceEvent.ORDER_COMPLETED },
+];
+
+const interceptor = new NetworkInterceptor(patterns, {
+    onRequest: (url, method, body) => { /* 요청 감지 */ },
+    onResponse: (url, status, body) => { /* 응답 감지 */ },
+});
+
+interceptor.start();
+// ...
+interceptor.stop(); // 원본 함수 복원
+```
+
+### PlatformAdapter
+
+플랫폼별 데이터 추출 계약을 정의하는 인터페이스입니다:
+
+```typescript
+interface PlatformAdapter {
+    readonly name: string;
+    initialize(config: EcommercePluginConfig, context: PluginContext): void;
+    cleanup(): void;
+    detectPageType(): PageType;
+    extractProduct(): Product | null;
+    extractCartItems(): CartItem[];
+    extractOrder(): OrderData | null;
+    getPlatformMeta(): Record<string, any>;
+}
+```
+
+### 이벤트 타입
+
+```typescript
+enum EcommerceEvent {
+    PAGE_VIEWED              // 페이지 조회
+    PRODUCT_VIEWED           // 상품 상세 조회
+    PRODUCT_ADDED_TO_CART    // 장바구니 추가
+    PRODUCT_REMOVED_FROM_CART // 장바구니 제거
+    CART_VIEWED              // 장바구니 조회
+    CART_UPDATED             // 장바구니 수량 변경
+    PRODUCT_ADDED_TO_WISHLIST // 위시리스트 추가
+    CHECKOUT_STARTED         // 주문서 진입
+    EXTERNAL_PAYMENT_INITIATED // 외부 결제 시작
+    ORDER_COMPLETED          // 주문 완료
+}
+```
+
+### 데이터 타입
+
+| 타입 | 설명 |
+|------|------|
+| `Product` | 상품 정보 (product_id, name, price, sku, ...) |
+| `CartItem` | 장바구니 아이템 (Product + quantity) |
+| `OrderItem` | 주문 아이템 (Product + quantity + item_total) |
+| `OrderData` | 주문 데이터 (order_id, total, items, ...) |
+
+### 설정
+
+```typescript
+interface EcommercePluginConfig {
+    trackPageViews?: boolean;        // 페이지뷰 자동 추적 (기본: true)
+    trackNetworkRequests?: boolean;  // 네트워크 인터셉션 (기본: true)
+    trackDomInteractions?: boolean;  // DOM 인터랙션 추적 (기본: true)
+    deduplicationWindow?: number;    // 중복 방지 윈도우 ms (기본: 2000)
+    debug?: boolean;                 // 디버그 로그 (기본: false)
+}
+```
+
+## 새 플랫폼 플러그인 만들기
+
+1. `BaseEcommercePlugin`을 상속
+2. `PlatformAdapter`를 구현하여 플랫폼별 데이터 추출 로직 작성
+3. `getNetworkPatterns()`에서 인터셉트할 API URL 패턴 반환
+4. `handleNetworkRequest()`에서 인터셉트된 요청을 이벤트로 변환
+
+참조 구현: [`@vircle/plugin-cafe24`](../plugin-cafe24)

package/dist/index.d.mts

@@ -0,0 +1,231 @@
+import { PluginContext, VirclePlugin, PluginHooks } from '@vircle/sdk-core-ts';
+
+/**
+ * E-commerce plugin core types
+ */
+
+/**
+ * Standard e-commerce event names
+ */
+declare enum EcommerceEvent {
+    PAGE_VIEWED = "page_viewed",
+    PRODUCT_VIEWED = "product_viewed",
+    PRODUCT_ADDED_TO_CART = "product_added_to_cart",
+    PRODUCT_REMOVED_FROM_CART = "product_removed_from_cart",
+    CART_VIEWED = "cart_viewed",
+    CART_UPDATED = "cart_updated",
+    PRODUCT_ADDED_TO_WISHLIST = "product_added_to_wishlist",
+    CHECKOUT_STARTED = "checkout_started",
+    EXTERNAL_PAYMENT_INITIATED = "external_payment_initiated",
+    ORDER_COMPLETED = "order_completed"
+}
+/**
+ * Product sub-object schema
+ */
+interface Product {
+    product_id: string;
+    name: string;
+    price: number;
+    sku?: string;
+    category?: string;
+    brand?: string;
+    variant?: string;
+    quantity?: number;
+    currency?: string;
+    image_url?: string;
+    url?: string;
+    position?: number;
+}
+/**
+ * Cart item sub-object schema
+ */
+interface CartItem extends Product {
+    quantity: number;
+    item_total?: number;
+}
+/**
+ * Order item sub-object schema
+ */
+interface OrderItem extends Product {
+    quantity: number;
+    item_total: number;
+    discount?: number;
+}
+/**
+ * E-commerce plugin configuration
+ */
+interface EcommercePluginConfig {
+    /** Enable automatic page view tracking */
+    trackPageViews?: boolean;
+    /** Enable network request interception */
+    trackNetworkRequests?: boolean;
+    /** Enable DOM-based tracking */
+    trackDomInteractions?: boolean;
+    /** Custom URL patterns to intercept */
+    urlPatterns?: NetworkPattern[];
+    /** Event deduplication window in ms */
+    deduplicationWindow?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Network URL pattern for interception
+ */
+interface NetworkPattern {
+    /** URL pattern (string match or regex) */
+    pattern: string | RegExp;
+    /** HTTP method filter */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Event to emit when matched */
+    event: EcommerceEvent;
+}
+/**
+ * Platform adapter interface — contract for platform-specific implementations
+ */
+interface PlatformAdapter {
+    /** Platform name */
+    readonly name: string;
+    /** Initialize adapter */
+    initialize(config: EcommercePluginConfig, context: PluginContext): void;
+    /** Cleanup adapter resources */
+    cleanup(): void;
+    /** Detect current page type */
+    detectPageType(): PageType;
+    /** Extract product data from current page */
+    extractProduct(): Product | null;
+    /** Extract cart items from current page */
+    extractCartItems(): CartItem[];
+    /** Extract order data from current page */
+    extractOrder(): OrderData | null;
+    /** Get platform-specific metadata */
+    getPlatformMeta(): Record<string, any>;
+}
+/**
+ * Page types for e-commerce sites
+ */
+declare enum PageType {
+    HOME = "home",
+    PRODUCT_LIST = "product_list",
+    PRODUCT_DETAIL = "product_detail",
+    CART = "cart",
+    CHECKOUT = "checkout",
+    ORDER_COMPLETE = "order_complete",
+    SEARCH_RESULTS = "search_results",
+    MY_PAGE = "my_page",
+    OTHER = "other"
+}
+/**
+ * Order data structure
+ */
+interface OrderData {
+    order_id: string;
+    total: number;
+    subtotal?: number;
+    tax?: number;
+    shipping?: number;
+    discount?: number;
+    currency?: string;
+    payment_method?: string;
+    items: OrderItem[];
+}
+/**
+ * Network intercept callback
+ */
+interface NetworkInterceptCallback {
+    onRequest?(url: string, method: string, body?: any): void;
+    onResponse?(url: string, status: number, body?: any): void;
+}
+
+/**
+ * Network interceptor for capturing fetch/XHR requests
+ * Patches window.fetch and XMLHttpRequest to intercept matching API calls
+ */
+
+declare class NetworkInterceptor {
+    private patterns;
+    private callback;
+    private originalFetch?;
+    private originalXHROpen?;
+    private originalXHRSend?;
+    private isActive;
+    constructor(patterns: NetworkPattern[], callback: NetworkInterceptCallback);
+    /**
+     * Start intercepting network requests
+     */
+    start(): void;
+    /**
+     * Stop intercepting and restore original functions
+     */
+    stop(): void;
+    /**
+     * Check if a URL matches any registered pattern
+     */
+    matchUrl(url: string, method?: string): NetworkPattern | undefined;
+    private patchFetch;
+    private patchXHR;
+    private restoreFetch;
+    private restoreXHR;
+}
+
+/**
+ * Base e-commerce plugin that platform-specific plugins extend
+ */
+
+declare abstract class BaseEcommercePlugin implements VirclePlugin {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    abstract readonly description: string;
+    protected context?: PluginContext;
+    protected pluginConfig: EcommercePluginConfig;
+    protected adapter?: PlatformAdapter;
+    protected interceptor?: NetworkInterceptor;
+    /** 모든 이벤트에 자동 첨부되는 글로벌 프로퍼티 (크로스 도메인 어트리뷰션 등) */
+    protected globalProperties: Record<string, unknown>;
+    private recentEvents;
+    private dedupeTimers;
+    private navigationCleanup?;
+    hooks?: PluginHooks;
+    /**
+     * Get network patterns for this platform
+     */
+    protected abstract getNetworkPatterns(): NetworkPattern[];
+    /**
+     * Create the platform adapter
+     */
+    protected abstract createAdapter(): PlatformAdapter;
+    /**
+     * Called after base initialization, override for platform-specific setup
+     */
+    protected onInitialized(): void;
+    /**
+     * Called before cleanup, override for platform-specific teardown
+     */
+    protected onCleanup(): void;
+    initialize(config: EcommercePluginConfig, context: PluginContext): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Track an e-commerce event with deduplication
+     */
+    protected trackEvent(event: EcommerceEvent, properties: Record<string, any>): void;
+    /**
+     * Handle intercepted network request — override in subclass for specific behavior
+     */
+    protected handleNetworkRequest(_url: string, _method: string, _body?: any): void;
+    /**
+     * Handle intercepted network response — override in subclass for specific behavior
+     */
+    protected handleNetworkResponse(_url: string, _status: number, _body?: any): void;
+    /**
+     * Handle page navigation
+     */
+    protected handlePageNavigation(url: string): void;
+    private setupNavigationTracking;
+    /**
+     * URL의 캠페인 파라미터(UTM + 광고 ID)를 수집하여 globalProperties에 설정.
+     * sessionStorage를 사용하여 MPA 페이지 전환 간에도 유지.
+     */
+    private initCampaignParams;
+    private getDefaultConfig;
+}
+
+export { BaseEcommercePlugin, type CartItem, EcommerceEvent, type EcommercePluginConfig, type NetworkInterceptCallback, NetworkInterceptor, type NetworkPattern, type OrderData, type OrderItem, PageType, type PlatformAdapter, type Product };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { PluginContext, VirclePlugin, PluginHooks } from '@vircle/sdk-core-ts';
+
+/**
+ * E-commerce plugin core types
+ */
+
+/**
+ * Standard e-commerce event names
+ */
+declare enum EcommerceEvent {
+    PAGE_VIEWED = "page_viewed",
+    PRODUCT_VIEWED = "product_viewed",
+    PRODUCT_ADDED_TO_CART = "product_added_to_cart",
+    PRODUCT_REMOVED_FROM_CART = "product_removed_from_cart",
+    CART_VIEWED = "cart_viewed",
+    CART_UPDATED = "cart_updated",
+    PRODUCT_ADDED_TO_WISHLIST = "product_added_to_wishlist",
+    CHECKOUT_STARTED = "checkout_started",
+    EXTERNAL_PAYMENT_INITIATED = "external_payment_initiated",
+    ORDER_COMPLETED = "order_completed"
+}
+/**
+ * Product sub-object schema
+ */
+interface Product {
+    product_id: string;
+    name: string;
+    price: number;
+    sku?: string;
+    category?: string;
+    brand?: string;
+    variant?: string;
+    quantity?: number;
+    currency?: string;
+    image_url?: string;
+    url?: string;
+    position?: number;
+}
+/**
+ * Cart item sub-object schema
+ */
+interface CartItem extends Product {
+    quantity: number;
+    item_total?: number;
+}
+/**
+ * Order item sub-object schema
+ */
+interface OrderItem extends Product {
+    quantity: number;
+    item_total: number;
+    discount?: number;
+}
+/**
+ * E-commerce plugin configuration
+ */
+interface EcommercePluginConfig {
+    /** Enable automatic page view tracking */
+    trackPageViews?: boolean;
+    /** Enable network request interception */
+    trackNetworkRequests?: boolean;
+    /** Enable DOM-based tracking */
+    trackDomInteractions?: boolean;
+    /** Custom URL patterns to intercept */
+    urlPatterns?: NetworkPattern[];
+    /** Event deduplication window in ms */
+    deduplicationWindow?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Network URL pattern for interception
+ */
+interface NetworkPattern {
+    /** URL pattern (string match or regex) */
+    pattern: string | RegExp;
+    /** HTTP method filter */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Event to emit when matched */
+    event: EcommerceEvent;
+}
+/**
+ * Platform adapter interface — contract for platform-specific implementations
+ */
+interface PlatformAdapter {
+    /** Platform name */
+    readonly name: string;
+    /** Initialize adapter */
+    initialize(config: EcommercePluginConfig, context: PluginContext): void;
+    /** Cleanup adapter resources */
+    cleanup(): void;
+    /** Detect current page type */
+    detectPageType(): PageType;
+    /** Extract product data from current page */
+    extractProduct(): Product | null;
+    /** Extract cart items from current page */
+    extractCartItems(): CartItem[];
+    /** Extract order data from current page */
+    extractOrder(): OrderData | null;
+    /** Get platform-specific metadata */
+    getPlatformMeta(): Record<string, any>;
+}
+/**
+ * Page types for e-commerce sites
+ */
+declare enum PageType {
+    HOME = "home",
+    PRODUCT_LIST = "product_list",
+    PRODUCT_DETAIL = "product_detail",
+    CART = "cart",
+    CHECKOUT = "checkout",
+    ORDER_COMPLETE = "order_complete",
+    SEARCH_RESULTS = "search_results",
+    MY_PAGE = "my_page",
+    OTHER = "other"
+}
+/**
+ * Order data structure
+ */
+interface OrderData {
+    order_id: string;
+    total: number;
+    subtotal?: number;
+    tax?: number;
+    shipping?: number;
+    discount?: number;
+    currency?: string;
+    payment_method?: string;
+    items: OrderItem[];
+}
+/**
+ * Network intercept callback
+ */
+interface NetworkInterceptCallback {
+    onRequest?(url: string, method: string, body?: any): void;
+    onResponse?(url: string, status: number, body?: any): void;
+}
+
+/**
+ * Network interceptor for capturing fetch/XHR requests
+ * Patches window.fetch and XMLHttpRequest to intercept matching API calls
+ */
+
+declare class NetworkInterceptor {
+    private patterns;
+    private callback;
+    private originalFetch?;
+    private originalXHROpen?;
+    private originalXHRSend?;
+    private isActive;
+    constructor(patterns: NetworkPattern[], callback: NetworkInterceptCallback);
+    /**
+     * Start intercepting network requests
+     */
+    start(): void;
+    /**
+     * Stop intercepting and restore original functions
+     */
+    stop(): void;
+    /**
+     * Check if a URL matches any registered pattern
+     */
+    matchUrl(url: string, method?: string): NetworkPattern | undefined;
+    private patchFetch;
+    private patchXHR;
+    private restoreFetch;
+    private restoreXHR;
+}
+
+/**
+ * Base e-commerce plugin that platform-specific plugins extend
+ */
+
+declare abstract class BaseEcommercePlugin implements VirclePlugin {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    abstract readonly description: string;
+    protected context?: PluginContext;
+    protected pluginConfig: EcommercePluginConfig;
+    protected adapter?: PlatformAdapter;
+    protected interceptor?: NetworkInterceptor;
+    /** 모든 이벤트에 자동 첨부되는 글로벌 프로퍼티 (크로스 도메인 어트리뷰션 등) */
+    protected globalProperties: Record<string, unknown>;
+    private recentEvents;
+    private dedupeTimers;
+    private navigationCleanup?;
+    hooks?: PluginHooks;
+    /**
+     * Get network patterns for this platform
+     */
+    protected abstract getNetworkPatterns(): NetworkPattern[];
+    /**
+     * Create the platform adapter
+     */
+    protected abstract createAdapter(): PlatformAdapter;
+    /**
+     * Called after base initialization, override for platform-specific setup
+     */
+    protected onInitialized(): void;
+    /**
+     * Called before cleanup, override for platform-specific teardown
+     */
+    protected onCleanup(): void;
+    initialize(config: EcommercePluginConfig, context: PluginContext): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Track an e-commerce event with deduplication
+     */
+    protected trackEvent(event: EcommerceEvent, properties: Record<string, any>): void;
+    /**
+     * Handle intercepted network request — override in subclass for specific behavior
+     */
+    protected handleNetworkRequest(_url: string, _method: string, _body?: any): void;
+    /**
+     * Handle intercepted network response — override in subclass for specific behavior
+     */
+    protected handleNetworkResponse(_url: string, _status: number, _body?: any): void;
+    /**
+     * Handle page navigation
+     */
+    protected handlePageNavigation(url: string): void;
+    private setupNavigationTracking;
+    /**
+     * URL의 캠페인 파라미터(UTM + 광고 ID)를 수집하여 globalProperties에 설정.
+     * sessionStorage를 사용하여 MPA 페이지 전환 간에도 유지.
+     */
+    private initCampaignParams;
+    private getDefaultConfig;
+}
+
+export { BaseEcommercePlugin, type CartItem, EcommerceEvent, type EcommercePluginConfig, type NetworkInterceptCallback, NetworkInterceptor, type NetworkPattern, type OrderData, type OrderItem, PageType, type PlatformAdapter, type Product };