connectbase-client 1.5.0 → 1.7.0

package/dist/index.d.mts

@@ -119,6 +119,146 @@ declare class HttpClient {
     fetchRaw(url: string, init?: RequestInit): Promise<Response>;
 }
 
+interface AnalyticsConfig {
+    /** 자동 페이지뷰 추적 @default true */
+    trackPageViews?: boolean;
+    /** 커스텀 이벤트 활성화 @default true */
+    trackEvents?: boolean;
+    /** 세션 + heartbeat @default true */
+    trackSessions?: boolean;
+    /** 히트맵 (opt-in) @default false */
+    heatmap?: boolean;
+    /** 세션 녹화 (opt-in) @default false */
+    recording?: boolean;
+    /** 배치 크기 @default 10 */
+    batchSize?: number;
+    /** 배치 전송 간격 (ms) @default 5000 */
+    flushInterval?: number;
+    /** DNT 헤더 존중 @default true */
+    respectDoNotTrack?: boolean;
+    /** 디버그 모드 @default false */
+    debug?: boolean;
+}
+interface ConsentOptions {
+    analytics?: boolean;
+    heatmap?: boolean;
+    recording?: boolean;
+}
+interface AnalyticsEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: number;
+}
+declare class SessionManager {
+    private _sessionId;
+    private _visitorUid;
+    private _lastActivity;
+    private _isNewSession;
+    get sessionId(): string;
+    get visitorUid(): string;
+    get isNewSession(): boolean;
+    /** 활동 기록 — 세션 타임아웃 리셋 */
+    touch(): void;
+    /** 세션 강제 리셋 */
+    reset(): void;
+    private ensureSession;
+    private loadOrCreateVisitorUid;
+}
+declare class AnalyticsAPI {
+    private http;
+    private config;
+    private consent;
+    private session;
+    private storageWebId;
+    private memberId;
+    private eventQueue;
+    private batchTimer;
+    private isInitialized;
+    private heartbeatTimer;
+    private visibilityHandler;
+    private unloadHeartbeatHandler;
+    private popstateHandler;
+    private beforeUnloadHandler;
+    private origPushState;
+    private origReplaceState;
+    private heatmapClickHandler;
+    private heatmapScrollHandler;
+    private utm;
+    constructor(http: HttpClient);
+    /**
+     * Analytics 초기화
+     * @param storageWebId 웹 스토리지 ID
+     * @param config 설정 (선택)
+     */
+    init(storageWebId: string, config?: AnalyticsConfig): void;
+    /** Analytics 정리 */
+    destroy(): void;
+    /**
+     * 동의 설정 변경
+     */
+    setConsent(consent: ConsentOptions): void;
+    /** 현재 동의 상태 조회 */
+    getConsent(): ConsentOptions;
+    /**
+     * 페이지뷰 수동 추적
+     */
+    trackPageView(path?: string): void;
+    /**
+     * 커스텀 이벤트 추적
+     */
+    trackEvent(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * 사용자 식별 (로그인 시)
+     * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+     */
+    identify(memberId: string): void;
+    /**
+     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
+     * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     */
+    setMemberId(memberId: string | null): void;
+    /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
+    getMemberId(): string | null;
+    /**
+     * 히트맵 수집 활성화 (opt-in)
+     */
+    enableHeatmap(options?: {
+        click?: boolean;
+        scroll?: boolean;
+    }): void;
+    /**
+     * 세션 heartbeat 자동 전송 시작 (30초 간격)
+     */
+    enableHeartbeat(): void;
+    /** 큐에 있는 이벤트 즉시 전송 */
+    flush(): Promise<void>;
+    /** 세션 매니저 접근 (고급) */
+    getSession(): SessionManager;
+    private canTrack;
+    private isDNT;
+    private createBaseEvent;
+    private enqueue;
+    private flushQueue;
+    /** sendBeacon으로 동기 flush (beforeunload용) */
+    private flushSync;
+    private trackSessionStart;
+    private startBatchTimer;
+    private stopBatchTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** 하트비트를 큐에 넣어 배치 전송 */
+    private sendHeartbeat;
+    /** sendBeacon으로 하트비트 전송 (unload/visibility hidden용) */
+    private sendHeartbeatBeacon;
+    private setupAutoPageView;
+    private removeAutoPageView;
+    private removeHeatmapListeners;
+    private handleHeatmapClick;
+    private recordHeatmapEvent;
+    private heatmapQueue;
+    private log;
+}
+
 /** 앱 멤버 게스트 가입 응답 */
 interface GuestMemberSignInResponse {
     member_id: string;
@@ -184,7 +324,14 @@ declare class AuthAPI {
     private http;
     private guestMemberLoginPromise;
     private cachedGuestMemberTokenKey;
+    private analytics;
     constructor(http: HttpClient);
+    /**
+     * AnalyticsAPI 주입 — 로그인/가입/로그아웃 시 방문자 트래커에 member_id 를 전달하여
+     * 게스트 방문자를 회원과 연결한다. ConnectBase 컨스트럭터에서 내부적으로 호출된다.
+     */
+    _attachAnalytics(analytics: AnalyticsAPI): void;
+    private notifyVisitorTracker;
     /**
      * 앱의 인증 설정 조회
      * 어떤 로그인 방식이 허용되는지 확인합니다.
@@ -1359,17 +1506,23 @@ declare class DatabaseAPI {
     createGeoIndex(appId: string, tableId: string, data: CreateGeoIndexRequest): Promise<GeoIndex>;
     deleteGeoIndex(appId: string, tableId: string, indexId: string): Promise<void>;
     /**
-     * 테이블 릴레이션 목록 조회
+     * 테이블 릴레이션 목록 조회. `sourceTable` 생략 시 앱 전체의 릴레이션을 반환.
+     *
+     * 서버 경로: `GET /v1/apps/:appID/databases/relations[?source_table=...]`
      */
-    listRelations(appId: string, tableId: string): Promise<TableRelation[]>;
+    listRelations(appId: string, sourceTable?: string): Promise<TableRelation[]>;
     /**
-     * 릴레이션 생성
+     * 릴레이션 생성.
+     *
+     * 서버 경로: `POST /v1/apps/:appID/databases/relations` — body 내 `source_table`/`target_table` 로 테이블 지정.
      */
-    createRelation(appId: string, tableId: string, data: CreateRelationRequest): Promise<TableRelation>;
+    createRelation(appId: string, data: CreateRelationRequest): Promise<TableRelation>;
     /**
-     * 릴레이션 삭제
+     * 릴레이션 삭제. `relationId` 는 서버에서 발급한 UUID (listRelations 로 조회해 얻음).
+     *
+     * 서버 경로: `DELETE /v1/apps/:appID/databases/relations/:relationID`
      */
-    deleteRelation(appId: string, tableId: string, relationName: string): Promise<void>;
+    deleteRelation(appId: string, relationId: string): Promise<void>;
     /**
      * 트리거 목록 조회
      */
@@ -6258,137 +6411,6 @@ declare class QueueAPI {
     getInfo(queueID: string): Promise<QueueInfoResponse>;
 }
 
-interface AnalyticsConfig {
-    /** 자동 페이지뷰 추적 @default true */
-    trackPageViews?: boolean;
-    /** 커스텀 이벤트 활성화 @default true */
-    trackEvents?: boolean;
-    /** 세션 + heartbeat @default true */
-    trackSessions?: boolean;
-    /** 히트맵 (opt-in) @default false */
-    heatmap?: boolean;
-    /** 세션 녹화 (opt-in) @default false */
-    recording?: boolean;
-    /** 배치 크기 @default 10 */
-    batchSize?: number;
-    /** 배치 전송 간격 (ms) @default 5000 */
-    flushInterval?: number;
-    /** DNT 헤더 존중 @default true */
-    respectDoNotTrack?: boolean;
-    /** 디버그 모드 @default false */
-    debug?: boolean;
-}
-interface ConsentOptions {
-    analytics?: boolean;
-    heatmap?: boolean;
-    recording?: boolean;
-}
-interface AnalyticsEvent {
-    name: string;
-    properties?: Record<string, unknown>;
-    timestamp?: number;
-}
-declare class SessionManager {
-    private _sessionId;
-    private _visitorUid;
-    private _lastActivity;
-    private _isNewSession;
-    get sessionId(): string;
-    get visitorUid(): string;
-    get isNewSession(): boolean;
-    /** 활동 기록 — 세션 타임아웃 리셋 */
-    touch(): void;
-    /** 세션 강제 리셋 */
-    reset(): void;
-    private ensureSession;
-    private loadOrCreateVisitorUid;
-}
-declare class AnalyticsAPI {
-    private http;
-    private config;
-    private consent;
-    private session;
-    private storageWebId;
-    private eventQueue;
-    private batchTimer;
-    private isInitialized;
-    private heartbeatTimer;
-    private visibilityHandler;
-    private unloadHeartbeatHandler;
-    private popstateHandler;
-    private beforeUnloadHandler;
-    private origPushState;
-    private origReplaceState;
-    private heatmapClickHandler;
-    private heatmapScrollHandler;
-    private utm;
-    constructor(http: HttpClient);
-    /**
-     * Analytics 초기화
-     * @param storageWebId 웹 스토리지 ID
-     * @param config 설정 (선택)
-     */
-    init(storageWebId: string, config?: AnalyticsConfig): void;
-    /** Analytics 정리 */
-    destroy(): void;
-    /**
-     * 동의 설정 변경
-     */
-    setConsent(consent: ConsentOptions): void;
-    /** 현재 동의 상태 조회 */
-    getConsent(): ConsentOptions;
-    /**
-     * 페이지뷰 수동 추적
-     */
-    trackPageView(path?: string): void;
-    /**
-     * 커스텀 이벤트 추적
-     */
-    trackEvent(name: string, properties?: Record<string, unknown>): void;
-    /**
-     * 사용자 식별 (로그인 시)
-     */
-    identify(memberId: string): void;
-    /**
-     * 히트맵 수집 활성화 (opt-in)
-     */
-    enableHeatmap(options?: {
-        click?: boolean;
-        scroll?: boolean;
-    }): void;
-    /**
-     * 세션 heartbeat 자동 전송 시작 (30초 간격)
-     */
-    enableHeartbeat(): void;
-    /** 큐에 있는 이벤트 즉시 전송 */
-    flush(): Promise<void>;
-    /** 세션 매니저 접근 (고급) */
-    getSession(): SessionManager;
-    private canTrack;
-    private isDNT;
-    private createBaseEvent;
-    private enqueue;
-    private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
-    private flushSync;
-    private trackSessionStart;
-    private startBatchTimer;
-    private stopBatchTimer;
-    private startHeartbeat;
-    private stopHeartbeat;
-    /** 하트비트를 큐에 넣어 배치 전송 */
-    private sendHeartbeat;
-    /** sendBeacon으로 하트비트 전송 (unload/visibility hidden용) */
-    private sendHeartbeatBeacon;
-    private setupAutoPageView;
-    private removeAutoPageView;
-    private removeHeatmapListeners;
-    private handleHeatmapClick;
-    private recordHeatmapEvent;
-    private heatmapQueue;
-    private log;
-}
-
 /**
  * WebTransport-based Game Client
  *

package/dist/index.d.ts

@@ -119,6 +119,146 @@ declare class HttpClient {
     fetchRaw(url: string, init?: RequestInit): Promise<Response>;
 }
 
+interface AnalyticsConfig {
+    /** 자동 페이지뷰 추적 @default true */
+    trackPageViews?: boolean;
+    /** 커스텀 이벤트 활성화 @default true */
+    trackEvents?: boolean;
+    /** 세션 + heartbeat @default true */
+    trackSessions?: boolean;
+    /** 히트맵 (opt-in) @default false */
+    heatmap?: boolean;
+    /** 세션 녹화 (opt-in) @default false */
+    recording?: boolean;
+    /** 배치 크기 @default 10 */
+    batchSize?: number;
+    /** 배치 전송 간격 (ms) @default 5000 */
+    flushInterval?: number;
+    /** DNT 헤더 존중 @default true */
+    respectDoNotTrack?: boolean;
+    /** 디버그 모드 @default false */
+    debug?: boolean;
+}
+interface ConsentOptions {
+    analytics?: boolean;
+    heatmap?: boolean;
+    recording?: boolean;
+}
+interface AnalyticsEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: number;
+}
+declare class SessionManager {
+    private _sessionId;
+    private _visitorUid;
+    private _lastActivity;
+    private _isNewSession;
+    get sessionId(): string;
+    get visitorUid(): string;
+    get isNewSession(): boolean;
+    /** 활동 기록 — 세션 타임아웃 리셋 */
+    touch(): void;
+    /** 세션 강제 리셋 */
+    reset(): void;
+    private ensureSession;
+    private loadOrCreateVisitorUid;
+}
+declare class AnalyticsAPI {
+    private http;
+    private config;
+    private consent;
+    private session;
+    private storageWebId;
+    private memberId;
+    private eventQueue;
+    private batchTimer;
+    private isInitialized;
+    private heartbeatTimer;
+    private visibilityHandler;
+    private unloadHeartbeatHandler;
+    private popstateHandler;
+    private beforeUnloadHandler;
+    private origPushState;
+    private origReplaceState;
+    private heatmapClickHandler;
+    private heatmapScrollHandler;
+    private utm;
+    constructor(http: HttpClient);
+    /**
+     * Analytics 초기화
+     * @param storageWebId 웹 스토리지 ID
+     * @param config 설정 (선택)
+     */
+    init(storageWebId: string, config?: AnalyticsConfig): void;
+    /** Analytics 정리 */
+    destroy(): void;
+    /**
+     * 동의 설정 변경
+     */
+    setConsent(consent: ConsentOptions): void;
+    /** 현재 동의 상태 조회 */
+    getConsent(): ConsentOptions;
+    /**
+     * 페이지뷰 수동 추적
+     */
+    trackPageView(path?: string): void;
+    /**
+     * 커스텀 이벤트 추적
+     */
+    trackEvent(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * 사용자 식별 (로그인 시)
+     * 이후 모든 방문 배치에 `app_member_id`가 첨부되어 게스트 방문자가 회원으로 연결됩니다.
+     */
+    identify(memberId: string): void;
+    /**
+     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출)
+     * null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     */
+    setMemberId(memberId: string | null): void;
+    /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
+    getMemberId(): string | null;
+    /**
+     * 히트맵 수집 활성화 (opt-in)
+     */
+    enableHeatmap(options?: {
+        click?: boolean;
+        scroll?: boolean;
+    }): void;
+    /**
+     * 세션 heartbeat 자동 전송 시작 (30초 간격)
+     */
+    enableHeartbeat(): void;
+    /** 큐에 있는 이벤트 즉시 전송 */
+    flush(): Promise<void>;
+    /** 세션 매니저 접근 (고급) */
+    getSession(): SessionManager;
+    private canTrack;
+    private isDNT;
+    private createBaseEvent;
+    private enqueue;
+    private flushQueue;
+    /** sendBeacon으로 동기 flush (beforeunload용) */
+    private flushSync;
+    private trackSessionStart;
+    private startBatchTimer;
+    private stopBatchTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** 하트비트를 큐에 넣어 배치 전송 */
+    private sendHeartbeat;
+    /** sendBeacon으로 하트비트 전송 (unload/visibility hidden용) */
+    private sendHeartbeatBeacon;
+    private setupAutoPageView;
+    private removeAutoPageView;
+    private removeHeatmapListeners;
+    private handleHeatmapClick;
+    private recordHeatmapEvent;
+    private heatmapQueue;
+    private log;
+}
+
 /** 앱 멤버 게스트 가입 응답 */
 interface GuestMemberSignInResponse {
     member_id: string;
@@ -184,7 +324,14 @@ declare class AuthAPI {
     private http;
     private guestMemberLoginPromise;
     private cachedGuestMemberTokenKey;
+    private analytics;
     constructor(http: HttpClient);
+    /**
+     * AnalyticsAPI 주입 — 로그인/가입/로그아웃 시 방문자 트래커에 member_id 를 전달하여
+     * 게스트 방문자를 회원과 연결한다. ConnectBase 컨스트럭터에서 내부적으로 호출된다.
+     */
+    _attachAnalytics(analytics: AnalyticsAPI): void;
+    private notifyVisitorTracker;
     /**
      * 앱의 인증 설정 조회
      * 어떤 로그인 방식이 허용되는지 확인합니다.
@@ -1359,17 +1506,23 @@ declare class DatabaseAPI {
     createGeoIndex(appId: string, tableId: string, data: CreateGeoIndexRequest): Promise<GeoIndex>;
     deleteGeoIndex(appId: string, tableId: string, indexId: string): Promise<void>;
     /**
-     * 테이블 릴레이션 목록 조회
+     * 테이블 릴레이션 목록 조회. `sourceTable` 생략 시 앱 전체의 릴레이션을 반환.
+     *
+     * 서버 경로: `GET /v1/apps/:appID/databases/relations[?source_table=...]`
      */
-    listRelations(appId: string, tableId: string): Promise<TableRelation[]>;
+    listRelations(appId: string, sourceTable?: string): Promise<TableRelation[]>;
     /**
-     * 릴레이션 생성
+     * 릴레이션 생성.
+     *
+     * 서버 경로: `POST /v1/apps/:appID/databases/relations` — body 내 `source_table`/`target_table` 로 테이블 지정.
      */
-    createRelation(appId: string, tableId: string, data: CreateRelationRequest): Promise<TableRelation>;
+    createRelation(appId: string, data: CreateRelationRequest): Promise<TableRelation>;
     /**
-     * 릴레이션 삭제
+     * 릴레이션 삭제. `relationId` 는 서버에서 발급한 UUID (listRelations 로 조회해 얻음).
+     *
+     * 서버 경로: `DELETE /v1/apps/:appID/databases/relations/:relationID`
      */
-    deleteRelation(appId: string, tableId: string, relationName: string): Promise<void>;
+    deleteRelation(appId: string, relationId: string): Promise<void>;
     /**
      * 트리거 목록 조회
      */
@@ -6258,137 +6411,6 @@ declare class QueueAPI {
     getInfo(queueID: string): Promise<QueueInfoResponse>;
 }
 
-interface AnalyticsConfig {
-    /** 자동 페이지뷰 추적 @default true */
-    trackPageViews?: boolean;
-    /** 커스텀 이벤트 활성화 @default true */
-    trackEvents?: boolean;
-    /** 세션 + heartbeat @default true */
-    trackSessions?: boolean;
-    /** 히트맵 (opt-in) @default false */
-    heatmap?: boolean;
-    /** 세션 녹화 (opt-in) @default false */
-    recording?: boolean;
-    /** 배치 크기 @default 10 */
-    batchSize?: number;
-    /** 배치 전송 간격 (ms) @default 5000 */
-    flushInterval?: number;
-    /** DNT 헤더 존중 @default true */
-    respectDoNotTrack?: boolean;
-    /** 디버그 모드 @default false */
-    debug?: boolean;
-}
-interface ConsentOptions {
-    analytics?: boolean;
-    heatmap?: boolean;
-    recording?: boolean;
-}
-interface AnalyticsEvent {
-    name: string;
-    properties?: Record<string, unknown>;
-    timestamp?: number;
-}
-declare class SessionManager {
-    private _sessionId;
-    private _visitorUid;
-    private _lastActivity;
-    private _isNewSession;
-    get sessionId(): string;
-    get visitorUid(): string;
-    get isNewSession(): boolean;
-    /** 활동 기록 — 세션 타임아웃 리셋 */
-    touch(): void;
-    /** 세션 강제 리셋 */
-    reset(): void;
-    private ensureSession;
-    private loadOrCreateVisitorUid;
-}
-declare class AnalyticsAPI {
-    private http;
-    private config;
-    private consent;
-    private session;
-    private storageWebId;
-    private eventQueue;
-    private batchTimer;
-    private isInitialized;
-    private heartbeatTimer;
-    private visibilityHandler;
-    private unloadHeartbeatHandler;
-    private popstateHandler;
-    private beforeUnloadHandler;
-    private origPushState;
-    private origReplaceState;
-    private heatmapClickHandler;
-    private heatmapScrollHandler;
-    private utm;
-    constructor(http: HttpClient);
-    /**
-     * Analytics 초기화
-     * @param storageWebId 웹 스토리지 ID
-     * @param config 설정 (선택)
-     */
-    init(storageWebId: string, config?: AnalyticsConfig): void;
-    /** Analytics 정리 */
-    destroy(): void;
-    /**
-     * 동의 설정 변경
-     */
-    setConsent(consent: ConsentOptions): void;
-    /** 현재 동의 상태 조회 */
-    getConsent(): ConsentOptions;
-    /**
-     * 페이지뷰 수동 추적
-     */
-    trackPageView(path?: string): void;
-    /**
-     * 커스텀 이벤트 추적
-     */
-    trackEvent(name: string, properties?: Record<string, unknown>): void;
-    /**
-     * 사용자 식별 (로그인 시)
-     */
-    identify(memberId: string): void;
-    /**
-     * 히트맵 수집 활성화 (opt-in)
-     */
-    enableHeatmap(options?: {
-        click?: boolean;
-        scroll?: boolean;
-    }): void;
-    /**
-     * 세션 heartbeat 자동 전송 시작 (30초 간격)
-     */
-    enableHeartbeat(): void;
-    /** 큐에 있는 이벤트 즉시 전송 */
-    flush(): Promise<void>;
-    /** 세션 매니저 접근 (고급) */
-    getSession(): SessionManager;
-    private canTrack;
-    private isDNT;
-    private createBaseEvent;
-    private enqueue;
-    private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
-    private flushSync;
-    private trackSessionStart;
-    private startBatchTimer;
-    private stopBatchTimer;
-    private startHeartbeat;
-    private stopHeartbeat;
-    /** 하트비트를 큐에 넣어 배치 전송 */
-    private sendHeartbeat;
-    /** sendBeacon으로 하트비트 전송 (unload/visibility hidden용) */
-    private sendHeartbeatBeacon;
-    private setupAutoPageView;
-    private removeAutoPageView;
-    private removeHeatmapListeners;
-    private handleHeatmapClick;
-    private recordHeatmapEvent;
-    private heatmapQueue;
-    private log;
-}
-
 /**
  * WebTransport-based Game Client
  *