connectbase-client 3.25.0 → 3.25.1

package/dist/index.d.mts

@@ -1,24 +1,149 @@
+interface ApiErrorDetail {
+    code: string;
+    message: string;
+    details?: unknown;
+}
 declare class ApiError extends Error {
     statusCode: number;
-    constructor(statusCode: number, message: string);
+    code: string | undefined;
+    details: unknown | undefined;
+    constructor(statusCode: number, message: string, code?: string, details?: unknown);
 }
 declare class AuthError extends Error {
     constructor(message: string);
 }
+/**
+ * GameError 는 game-server 가 surface 한 `error` 메시지 (createRoom/joinRoom/sendAction
+ * 응답 또는 broadcastScriptError) 를 client 측에서 일관된 형태로 다루기 위한 예외 클래스.
+ *
+ * 기존엔 모든 reject 가 `new Error(message)` 였어서 `code`/`phase`/`feature` 같은
+ * 분류 메타가 손실되어 SDK 사용자가 onError UI 분기를 만들 수 없었다 (NJB 사례,
+ * platform-issue 019e21dd / 2026-05-13).
+ *
+ * 사용 패턴:
+ * ```ts
+ * try {
+ *   await room.createRoom({ scriptName: 'my-script' })
+ * } catch (e) {
+ *   if (e instanceof GameError && e.code === 'SCRIPT_NOT_FOUND') {
+ *     console.error('script missing — available:', e.available)
+ *   }
+ * }
+ * ```
+ *
+ * onError 콜백도 동일하게 GameError 인스턴스로 surface 된다.
+ */
+declare class GameError extends Error {
+    /** server 가 분류한 에러 코드. literal 비교용은 GameErrorCode 참조. */
+    code: string;
+    /** Lua hook 단계 — 'onJoin'|'onLeave'|'onTick'|'onAction'. 비-lua 에러는 undefined. */
+    phase?: string;
+    /** FEATURE_DISABLED 시 비활성 feature 이름. */
+    feature?: string;
+    /** 영향받은 room id. */
+    roomId?: string;
+    /** `<appID>:<scriptName>` 형식의 attached script id. */
+    scriptId?: string;
+    /** broadcast 형태의 onAction 에러일 때, 액션을 일으킨 client (본인 아님 확인용). */
+    originClientId?: string;
+    /** SCRIPT_NOT_FOUND 응답 시 요청했던 scriptName. */
+    requested?: string;
+    /** SCRIPT_NOT_FOUND 응답 시 active 상태인 script 이름 목록. */
+    available?: string[];
+    constructor(init: {
+        code?: string;
+        message?: string;
+        phase?: string;
+        feature?: string;
+        roomId?: string;
+        scriptId?: string;
+        originClientId?: string;
+        requested?: string;
+        available?: string[];
+    });
+}
+
+interface AbortOptions {
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
+/**
+ * Recent API calls breadcrumb buffer — SDK 디버깅 / platform issue 발행 시 자동 첨부.
+ *
+ * **저장 정책 (PII 보호):**
+ *   - method, path (query string strip), status, duration_ms, timestamp 만 저장
+ *   - body / response body / 인증 토큰 미저장
+ *   - URL 내 secret-like 패턴 (key=, token=, password=) 자동 redact
+ *   - `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 는 path 만 (쿼리 strip)
+ */
+interface RecentApiCall {
+    method: string;
+    path: string;
+    status: number;
+    duration_ms: number;
+    timestamp: string;
+}
 
+type TokenPersistence = 'localStorage' | 'sessionStorage' | 'none';
 interface HttpClientConfig {
     baseUrl: string;
-    apiKey?: string;
+    /**
+     * Public Key (cb_pk_* 형식). 콘솔 → 설정 → API 에서 발급.
+     * 브라우저/클라이언트에서 사용 (Row Level Security 적용).
+     */
+    publicKey?: string;
+    /**
+     * Secret Key (cb_sk_* 형식). 사용자 프로필에서 발급.
+     * 서버 환경에서만 사용 (전체 권한, 절대 노출 금지).
+     */
+    secretKey?: string;
     accessToken?: string;
     refreshToken?: string;
+    /**
+     * 토큰 저장 방식. **기본값은 'none' (메모리 저장)**.
+     * XSS 취약점이 하나라도 있을 경우 영구 저장은 즉시 전 세션 탈취로 이어지므로,
+     * 영구 저장 옵션은 위험을 이해하고 명시적으로 선택한 경우에만 사용한다.
+     *
+     * - 'none' (권장·기본값): access token 만 메모리 저장. refresh token 은 서버가 발급한
+     *   HttpOnly cookie 로만 보관되어 JS 가 접근할 수 없다 (XSS 시 탈취 불가). 새로고침 후에는
+     *   `autoRestoreSession`(기본 true) 으로 cookie 만으로 자동 복구된다.
+     * - 'sessionStorage': 탭 종료 시 삭제. JS 접근 가능 → XSS 로 탭 세션 탈취 가능
+     * - 'localStorage': 브라우저 종료 후에도 유지. JS 접근 가능 → XSS 로 영구 탈취 가능
+     */
+    persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 로부터 access token 을 자동 복구할지 여부.
+     * 기본값은 브라우저 환경에서 true. 비-브라우저(Node.js, RN) 에서는 무시된다.
+     *
+     * cookie 가 없는 경우(미로그인) 조용히 실패하며 콘솔 에러를 발생시키지 않는다.
+     */
+    autoRestoreSession?: boolean;
+    /**
+     * 요청별 기본 타임아웃(ms). 개별 호출의 `timeout` 이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 ApiError/AuthError 발생 시 호출된다.
+     * 운영 관측성(Sentry/Datadog/자체 엔드포인트)과 연결하기 위한 훅.
+     */
+    onError?: (error: ApiError | AuthError) => void;
     onTokenRefresh?: (tokens: {
         accessToken: string;
         refreshToken: string;
     }) => void;
     onAuthError?: (error: AuthError) => void;
     onTokenExpired?: () => void;
+    /**
+     * `/v1/auth/re-issue` 의 일시적 실패(5xx, 네트워크 오류, abort) 발생 시 호출.
+     * 이 경우 토큰은 폐기되지 않으며 `onTokenExpired` 도 호출되지 않는다 — 다음 호출에서
+     * backoff 만료 후 자동 재시도. 사용자에게 "연결이 잠시 불안정합니다" 같은 비파괴적 알림을
+     * 표시할 때 사용. `onAuthError` 도 함께 호출되므로 둘을 동시에 wiring 하면 중복 처리에 주의.
+     */
+    onTransientRefreshFailure?: (error: AuthError) => void;
 }
-interface RequestConfig {
+interface RequestConfig extends AbortOptions {
     skipAuth?: boolean;
     headers?: Record<string, string>;
 }
@@ -26,35 +151,574 @@ declare class HttpClient {
     private config;
     private isRefreshing;
     private refreshPromise;
+    private storageKey;
+    private refreshFailureCount;
+    private refreshLockedUntil;
+    /**
+     * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
+     * `client.support.getRecentCalls()` 로 외부 노출.
+     */
+    private recentCalls;
+    /**
+     * 부팅 시 fire-and-forget 으로 시작한 cookie 기반 복구 promise. `prepareHeaders` 가
+     * 인증 호출을 보내기 직전에 이 promise 를 await 해, 페이지 진입 직후 첫 API 호출이
+     * 메모리 토큰 빈 상태로 401 받는 race 를 막는다 (platform-issue 019e638d, 2026-05-26).
+     * 한 번 settle 되면 그 결과(메모리 적재 또는 미로그인)가 항상 반영되어 있다.
+     */
+    private bootRestorePromise;
     constructor(config: HttpClientConfig);
+    /**
+     * 페이지 진입 시 fire-and-forget 으로 시작된 cookie 복구 promise 를 SDK 가 등록한다.
+     * 같은 promise 가 `prepareHeaders` 에서 await 되어, 첫 인증 호출이 cookie 복구
+     * 완료 후 발화한다.
+     */
+    setBootRestorePromise(p: Promise<boolean>): void;
+    /** 최근 호출 ring buffer 스냅샷 (시간순). */
+    getRecentCalls(): RecentApiCall[];
+    /** 최근 호출 buffer clear (테스트/프라이버시 처리). */
+    clearRecentCalls(): void;
+    private warnIfUnsafePersistence;
     updateConfig(config: Partial<HttpClientConfig>): void;
     setTokens(accessToken: string, refreshToken: string): void;
     clearTokens(): void;
     /**
-     * API Key가 설정되어 있는지 확인
+     * OAuth redirect callback 직후 호출되어 HttpOnly cookie 를 부트스트랩한다.
+     *
+     * 배경: 콜백 흐름에서 서버가 redirect 응답에 Set-Cookie 를 함께 발급하지만, 일부 deployment /
+     * 브라우저 정책 / 사용자 설정 (3rd-party cookie 차단 등) 환경에서 이 Set-Cookie 가 브라우저에
+     * 저장되지 않는다. `persistence='none'` 모드에서는 토큰이 메모리에만 있고 cookie 가 없는 상태로
+     * 페이지 새로고침이 발생하면 `/v1/auth/re-issue` 가 401 으로 떨어져 강제 로그아웃되는 회귀가
+     * 있다 (platform-issue 019e3960, 2026-05-18).
+     *
+     * 이 메서드는 메모리의 refresh token 으로 한 번 `/v1/auth/re-issue` 를 호출해 서버가 cookie 를
+     * 명시적으로 발급하도록 유도한다. 백엔드는 Bearer + `X-Public-Key` 조합을 SDK 호출 신호로
+     * 인식해 응답에 `cb_member_refresh_token` cookie 를 함께 내려준다.
+     *
+     * persistence='localStorage' / 'sessionStorage' 모드는 새로고침 후에도 메모리 복구가 가능하므로
+     * 호출하지 않는다 (rotation 만 일어나 비용만 증가). 비-브라우저 환경에서도 cookie 자체가 없으므로
+     * 호출하지 않는다.
+     */
+    bootstrapRefreshCookie(): Promise<void>;
+    private get persistence();
+    private getStorage;
+    /**
+     * AuthAPI 등 내부 사용자가 "현재 persistence 설정된 스토리지"를 확인할 수 있도록 노출.
+     * persistence='none' 이면 null. XSS 완화 기본값을 공유하기 위함.
+     */
+    getPersistenceStorage(): Storage | null;
+    private buildStorageKey;
+    private persistTokens;
+    private restoreTokens;
+    private removePersistedTokens;
+    /**
+     * Public Key 가 설정되어 있는지 확인
      */
-    hasApiKey(): boolean;
+    hasPublicKey(): boolean;
     /**
-     * API Key 반환
+     * Public Key 반환
      */
-    getApiKey(): string | undefined;
+    getPublicKey(): string | undefined;
+    /**
+     * Secret Key 가 설정되어 있는지 확인
+     */
+    hasSecretKey(): boolean;
+    /**
+     * Secret Key 반환
+     */
+    getSecretKey(): string | undefined;
+    /**
+     * 현재 설정된 자격증명 반환.
+     *
+     * publicKey 가 있으면 그걸 반환한다 (X-Public-Key 헤더 = 앱 식별용 = cb_pk_*).
+     * publicKey 가 없고 secretKey 만 있는 경우는 secretKey 로 폴백 — 단, 서버는
+     * cb_sk_ 가 X-Public-Key 에 실리면 거부하므로 의도된 401 이 나간다(앱 식별 불가).
+     *
+     * secretKey 의 admin 권한은 별도로 Authorization: Bearer 로 보낸다. 그 처리는
+     * prepareHeaders 안에서 publicKey + secretKey 가 함께 있을 때 수행한다.
+     */
+    getCredential(): string | undefined;
     /**
      * Access Token 반환
      */
     getAccessToken(): string | undefined;
+    /**
+     * JWT(Access Token) 가 설정되어 있는지 확인
+     */
+    hasJWT(): boolean;
     /**
      * Base URL 반환
      */
     getBaseUrl(): string;
     private refreshAccessToken;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 복구한다.
+     *
+     * 동작:
+     *   - 메모리에 access token 이 이미 있으면 그대로 반환 (true).
+     *   - 없으면 `/v1/auth/re-issue` 를 cookie 만으로 호출. cookie 가 있으면 access token 회복.
+     *   - cookie 가 없거나(미로그인) 만료된 경우 조용히 false 반환 (콘솔 에러 없음).
+     *
+     * 비-브라우저 환경에서는 cookie 흐름이 없으므로 즉시 false 반환.
+     */
+    tryRestoreSessionFromCookie(): Promise<boolean>;
+    private emitError;
     private isTokenExpired;
     private prepareHeaders;
     private handleResponse;
+    /**
+     * AbortController 를 관리하며 fetch 호출을 실행. 타임아웃/외부 signal 병합.
+     *
+     * 401 자동 복구: 인증 호출이 401 을 받으면 cookie 기반 복구를 *한 번* 시도하고 retry 한다.
+     * 메모리 토큰이 만료/누락 + cookie 는 살아 있는 경우를 자동으로 회복시켜,
+     * 페이지 진입 직후 race 로 401 을 받은 첫 호출이 사용자 흐름을 차단하지 않게 한다
+     * (platform-issue 019e638d, 2026-05-26). retry 는 1회 한정 — 무한 루프 차단.
+     */
+    private doFetch;
+    private tryFetchOnce;
     get<T>(url: string, config?: RequestConfig): Promise<T>;
     post<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
     put<T>(url: string, data: unknown, config?: RequestConfig): Promise<T>;
     patch<T>(url: string, data: unknown, config?: RequestConfig): Promise<T>;
     delete<T>(url: string, config?: RequestConfig): Promise<T>;
+    /**
+     * Raw fetch 요청 (SSE 스트리밍 등에 사용)
+     * 인증 헤더가 자동으로 추가됩니다. timeout 은 호출자가 직접 signal 로 관리해야 합니다
+     * (스트리밍 특성상 전역 timeout 을 강제하지 않음).
+     */
+    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;
+}
+/**
+ * 인기 페이지 목록 응답.
+ *
+ * 백엔드 `dto.PopularPagesResponse` 와 1:1 매핑.
+ */
+interface PopularPagesResponse {
+    pages: Array<{
+        page_path: string;
+        page_views: number;
+    }>;
+    start_date: number;
+    end_date: number;
+}
+/**
+ * 방문자 목록 응답.
+ *
+ * 백엔드 `dto.VisitorListResponse` 와 1:1 매핑. `app_member_id` 는 게스트 방문자에는
+ * 없을 수 있다.
+ */
+interface VisitorListResponse {
+    visitors: Array<{
+        id: string;
+        visitor_uid: string;
+        app_member_id?: string;
+        total_visits: number;
+        total_page_views: number;
+        referrer?: string;
+        last_ip?: string;
+        country?: string;
+        is_bot: boolean;
+        first_visit_at: string;
+        last_visit_at: string;
+    }>;
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+/**
+ * 페이지 전환 플로우(Sankey) 응답.
+ *
+ * 백엔드 `dto.NavigationFlowResponse` 와 1:1 매핑. `nodes` 는 페이지, `links` 는 전환.
+ */
+interface NavigationFlowResponse {
+    nodes: Array<{
+        id: string;
+        label: string;
+        value: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        value: number;
+    }>;
+}
+/**
+ * 조회 메서드 공통 옵션.
+ *
+ * `start_date` / `end_date` 는 백엔드가 정수형 epoch-day 또는 yyyymmdd 로 다루는 값
+ * (서비스 메서드 시그니처 기준 int). 0 또는 미지정 시 기본 기간을 사용.
+ */
+interface AnalyticsRangeOptions {
+    start_date?: number;
+    end_date?: number;
+    limit?: number;
+}
+interface VisitorListOptions {
+    limit?: number;
+    offset?: number;
+    /**
+     * 백엔드가 인식하는 정렬 키 — 외 값은 silent 로 default(`last_visit`) 처리됩니다.
+     *
+     * 1.12.0 에서 백엔드 실제 동작에 맞춰 enum 정정 (1.10/1.11 의 `total_visits`/
+     * `total_page_views` 는 백엔드에서 인식되지 않아 항상 default 분기였음).
+     */
+    sort_by?: 'last_visit' | 'visits' | 'page_views' | 'first_visit';
+}
+/**
+ * 멤버별 합산 방문자 그룹 항목.
+ *
+ * 한 명의 회원이 여러 디바이스/브라우저로 접속했을 때 visitor row 들을 합쳐 단일 row.
+ * 익명 visitor 는 `app_member_id == undefined` 로 단일 row 그대로 노출되며 `visitor_count == 1`.
+ *
+ * `visitor_count` 는 "디바이스 수" 가 아닌 **"추적 브라우저 인스턴스 수"** 를 의미합니다.
+ * 같은 디바이스에서 시크릿모드 + 일반모드는 visitor 2 = visitor_count 2 로 카운트됩니다.
+ */
+interface VisitorGroupItem {
+    app_member_id?: string;
+    /** 익명 visitor row 의 경우 단일 visitor_uid. 회원 그룹은 visitor_uids 참조. */
+    visitor_uid?: string;
+    /** 회원 그룹에 속한 visitor_uid 목록. 익명 row 는 undefined. */
+    visitor_uids?: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface VisitorGroupListResponse {
+    groups: VisitorGroupItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface VisitorByMemberResponse {
+    app_member_id: string;
+    visitor_uids: string[];
+    visitor_count: number;
+    total_visits: number;
+    total_page_views: number;
+    first_visit_at: string;
+    last_visit_at: string;
+    country?: string;
+    is_bot: boolean;
+}
+interface MergeVisitorsRequest {
+    source_visitor_uid: string;
+    /** target_visitor_uid 또는 target_member_id 중 하나는 필수. */
+    target_visitor_uid?: string;
+    target_member_id?: string;
+}
+interface MergeVisitorsResponse {
+    success: boolean;
+    target_visitor_id: string;
+    moved_records: number;
+    message?: string;
+}
+declare class SessionManager {
+    private _sessionId;
+    private _visitorUid;
+    private _lastActivity;
+    private _isNewSession;
+    get sessionId(): string;
+    get visitorUid(): string;
+    get isNewSession(): boolean;
+    /** 활동 기록 — 세션 타임아웃 리셋 */
+    touch(): void;
+    /** 세션 강제 리셋 */
+    reset(): void;
+    /**
+     * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+     *
+     * 사용 시점:
+     * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+     * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+     *
+     * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+     * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+     * 데이터 오염이 차단된다.
+     */
+    regenerateVisitorUid(): string;
+    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` 가 첨부되어 새 활동은 회원으로 기록됩니다.
+     * 추가로 **현재 visitor_uid 의 기존 익명 활동을 즉시 회원에게 backfill** 하기 위해
+     * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
+     * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
+     *
+     * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+     * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+     * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+     * 즉시 회원으로 기록되도록 자가 복구한다.
+     *
+     * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
+     *
+     * @example
+     * ```ts
+     * // 로그인 성공 직후
+     * const member = await cb.auth.signInMember({ login_id, password })
+     * cb.analytics.identify(member.member_id)
+     * ```
+     */
+    identify(memberId: string): void;
+    /**
+     * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+     * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+     *
+     * 동작:
+     * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+     * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+     * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+     * 4. heatmap 큐도 함께 비움
+     *
+     * @example
+     * ```ts
+     * // 로그아웃 핸들러
+     * await cb.auth.signOut()
+     * cb.analytics.reset()
+     * ```
+     */
+    reset(): void;
+    /**
+     * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
+     *
+     * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+     * 데이터 오염 방지를 위해 `reset()` 를 권장).
+     */
+    setMemberId(memberId: string | null): void;
+    /**
+     * 백엔드 link-member 엔드포인트 한 번 호출 — 즉시 backfill 트리거.
+     *
+     * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
+     *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+     *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+     *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
+     * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
+     */
+    private linkMemberSilent;
+    /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
+    getMemberId(): string | null;
+    /**
+     * 히트맵 수집 활성화 (opt-in)
+     */
+    enableHeatmap(options?: {
+        click?: boolean;
+        scroll?: boolean;
+    }): void;
+    /**
+     * 세션 heartbeat 자동 전송 시작 (30초 간격)
+     */
+    enableHeartbeat(): void;
+    /**
+     * 큐에 있는 이벤트 즉시 전송.
+     *
+     * 기본적으로 이벤트는 배치(10개) 또는 주기(5초)로 flush 되지만, 페이지 이탈 직전이나
+     * 결정적 이벤트(결제 완료 등)는 수동으로 `flush()` 를 호출해 전송 지연을 줄일 수 있다.
+     *
+     * @returns 서버 응답 완료 시까지 대기하는 Promise
+     *
+     * @example
+     * ```ts
+     * // 결제 완료 직후 이탈에 대비해 즉시 flush
+     * await cb.analytics.track('purchase_completed', { order_id: '123' })
+     * await cb.analytics.flush()
+     * window.location.href = '/thank-you'
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * 인기 페이지 조회 (콘솔 JWT 또는 User Secret Key `cb_sk_` 인증 필요).
+     *
+     * 브라우저 환경에서 Public Key(`cb_pk_`) 만 가진 SDK 인스턴스로는 호출이 차단된다.
+     * Functions / 어드민 앱 등 cb_sk_ 환경에서 사용하라.
+     *
+     * @param storageWebId 조회할 웹스토리지 ID. 미지정 시 `init()` 에 전달된 ID 사용.
+     * @param options 기간/limit 옵션
+     * @example
+     * ```ts
+     * const { pages } = await cb.analytics.getPopularPages('019d8...', { limit: 20 })
+     * ```
+     */
+    getPopularPages(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<PopularPagesResponse>;
+    /**
+     * 페이지 전환 플로우(Sankey) 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getNavigationFlow(storageWebId?: string, options?: AnalyticsRangeOptions): Promise<NavigationFlowResponse>;
+    /**
+     * 방문자 목록 조회 — JWT/cb_sk_ 인증 필요.
+     */
+    getVisitors(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorListResponse>;
+    /**
+     * 멤버별 합산 방문자 그룹 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * `getVisitors` 와 달리 visitor row 들을 `app_member_id` 로 합쳐 단일 row 로 반환.
+     * 같은 사람이 PC + 모바일 + 태블릿으로 접속한 경우 visitor 3개 → 그룹 1개.
+     * 익명 visitor 는 단일 row 로 그대로 포함되어 페이지네이션이 일관됨.
+     *
+     * @example
+     * ```ts
+     * const { groups } = await cb.analytics.getVisitorGroups('019d8...', { limit: 50 })
+     * for (const g of groups) {
+     *     if (g.app_member_id) console.log(`${g.app_member_id}: ${g.visitor_count} 디바이스`)
+     * }
+     * ```
+     */
+    getVisitorGroups(storageWebId?: string, options?: VisitorListOptions): Promise<VisitorGroupListResponse>;
+    /**
+     * 단건 멤버 합산 방문자 조회 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 어드민 회원 상세 페이지처럼 **한 명만 필요**할 때. 페이지네이션 풀 다운 없이
+     * 한 번의 호출로 합산 결과 반환.
+     *
+     * @example
+     * ```ts
+     * const v = await cb.analytics.getVisitorByMember('019d8...', memberId)
+     * console.log(`${v.visitor_count} 디바이스, 총 ${v.total_page_views} pv`)
+     * ```
+     */
+    getVisitorByMember(storageWebId: string | undefined, memberId: string): Promise<VisitorByMemberResponse>;
+    /**
+     * 두 visitor 를 한 사람으로 통합하는 admin 작업 — JWT/cb_sk_ 인증 필요. (1.11+)
+     *
+     * 외부 인증 시스템에서 두 visitor 가 동일인임을 알았을 때 사용. source 의 자식 레코드
+     * (page_views, daily, custom_events, experiment_assignments, heatmap_events,
+     * session_recordings) 를 target 으로 옮기고 source visitor 는 삭제됨.
+     *
+     * @param request 둘 중 하나 필수: `target_visitor_uid` 또는 `target_member_id`.
+     * @example
+     * ```ts
+     * await cb.analytics.mergeVisitors('019d8...', {
+     *     source_visitor_uid: 'old-uid',
+     *     target_member_id: '01a...',
+     * })
+     * ```
+     */
+    mergeVisitors(storageWebId: string | undefined, request: MergeVisitorsRequest): Promise<MergeVisitorsResponse>;
+    /**
+     * 조회 메서드 공통 가드 — Public Key 인증 SDK 인스턴스에서는 명확한 에러를 던진다.
+     * 백엔드 라우트는 cb_pk_ 를 거부하므로 호출 자체를 막는 것이 디버깅에 유리.
+     */
+    private requireServerSideStorageId;
+    /**
+     * 세션 매니저 접근 (고급 사용자용).
+     *
+     * 외부에서 세션 ID 를 읽어 자체 로깅에 합치거나 강제 세션 종료/재시작이 필요한 경우
+     * 사용. 일반적으로는 AnalyticsAPI 가 내부적으로 세션을 관리하므로 호출할 필요가 없다.
+     *
+     * @returns 내부 SessionManager 인스턴스
+     */
+    getSession(): SessionManager;
+    private canTrack;
+    private isDNT;
+    private createBaseEvent;
+    private enqueue;
+    private flushQueue;
+    /**
+     * sendBeacon 으로 동기 flush (beforeunload 용).
+     *
+     * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+     * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+     * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+     */
+    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;
 }
 
 /** 앱 멤버 게스트 가입 응답 */
@@ -93,16 +757,20 @@ interface MemberInfoResponse {
     member_id: string;
     nickname: string;
     is_active: boolean;
-    custom_data: Record<string, any>;
+    custom_data: Record<string, unknown>;
+    /** 멤버 이메일 (EMAIL identity 에서 추출, 없으면 빈 문자열) */
+    email?: string;
+    /** 멤버 역할 — RLS 규칙에서 `auth.role` 로 참조 (예: "admin", "moderator") */
+    role?: string;
 }
 /** 앱 멤버 custom_data 수정 요청 */
 interface UpdateCustomDataRequest {
-    custom_data: Record<string, any>;
+    custom_data: Record<string, unknown>;
 }
 /** 앱 멤버 custom_data 수정 응답 */
 interface UpdateCustomDataResponse {
     member_id: string;
-    custom_data: Record<string, any>;
+    custom_data: Record<string, unknown>;
 }
 /** 앱 인증 설정 응답 */
 interface AuthSettingsResponse {
@@ -118,7 +786,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;
     /**
      * 앱의 인증 설정 조회
      * 어떤 로그인 방식이 허용되는지 확인합니다.
@@ -208,6 +883,44 @@ declare class AuthAPI {
      * ```
      */
     updateCustomData(data: UpdateCustomDataRequest): Promise<UpdateCustomDataResponse>;
+    /**
+     * Admin: 다른 멤버의 정보를 수정합니다 (role / nickname / custom_data).
+     *
+     * 이 메서드는 RLS 의 `auth.role` 평가에 사용되는 `member.role` 필드를 set 할 수 있는
+     * 유일한 SDK 경로입니다. 보안상 AppMember 자신의 self-update 는 허용되지 않습니다
+     * (권한 상승 우회 차단) — 이 메서드는 cb_sk_ admin secret key 권한 컨텍스트에서만
+     * 호출 가능합니다.
+     *
+     * 사전 조건:
+     *   - ConnectBase 인스턴스가 `publicKey` 와 `secretKey` 를 모두 가지고 있어야 함
+     *   - secretKey 의 user 가 해당 앱에 권한을 가지고 있어야 함 (서버에서 검증)
+     *
+     * @example
+     * ```typescript
+     * const cb = new ConnectBase({ publicKey: 'cb_pk_...', secretKey: 'cb_sk_...' })
+     * await cb.auth.adminUpdateMember('member-uuid', { role: 'admin' })
+     *
+     * // role 해제
+     * await cb.auth.adminUpdateMember('member-uuid', { role: '' })
+     *
+     * // 다중 필드
+     * await cb.auth.adminUpdateMember('member-uuid', {
+     *     nickname: 'Alice',
+     *     role: 'editor',
+     *     custom_data: { level: 5 }
+     * })
+     * ```
+     */
+    adminUpdateMember(memberID: string, fields: {
+        nickname?: string;
+        role?: string;
+        custom_data?: Record<string, unknown>;
+    }): Promise<{
+        member_id: string;
+        nickname: string;
+        custom_data: Record<string, unknown>;
+        role: string;
+    }>;
     /**
      * 로그아웃
      */
@@ -223,26 +936,51 @@ declare class AuthAPI {
     private storeGuestMemberTokens;
 }
 
-type DataType = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+/**
+ * 서버(data-server `ent/schema/table.go` — `ValidSchemaTypes`) 가 허용하는 컬럼 타입 목록.
+ * - `string` / `number` / `int` : 문자열 / 숫자(float) / 정수
+ * - `bool` : 참/거짓 (JS 의 `boolean` 이 아니라 `bool` 입니다)
+ * - `uuid` : UUID 문자열
+ * - `date` : ISO-8601 날짜/시간
+ * - `object` / `array` : 중첩 JSON
+ */
+type DataType = 'string' | 'int' | 'number' | 'bool' | 'uuid' | 'date' | 'object' | 'array';
+/**
+ * 컬럼 정보 (Table.schema 맵에서 합성된 객체).
+ *
+ * 서버는 컬럼을 별도 레코드로 저장하지 않으므로 `id` 는 컬럼 이름과 동일하며,
+ * `order` 는 SDK 가 맵 순서대로 부여한 인덱스입니다. `created_at` 은 테이블의
+ * `created_at` 으로 대체됩니다.
+ */
 interface ColumnSchema {
+    /** 컬럼 이름과 동일 (서버 별도 ID 없음) */
     id: string;
     name: string;
     data_type: DataType;
     is_required: boolean;
-    default_value?: string;
-    validation_rule?: string;
-    order: number;
+    default_value?: unknown;
     description?: string;
+    encrypted?: boolean;
+    /** SDK 가 맵 순서대로 부여한 인덱스 */
+    order: number;
+    /** 테이블의 `created_at` (컬럼 개별 타임스탬프는 없음) */
     created_at: string;
+    /**
+     * @deprecated 서버가 지원하지 않습니다.
+     */
+    validation_rule?: string;
+    /**
+     * @deprecated 컬럼 개별 타임스탬프가 없습니다.
+     */
     updated_at?: string;
 }
 interface CreateColumnRequest {
     name: string;
     data_type: DataType;
-    is_required: boolean;
-    default_value?: string;
-    validation_rule?: string;
-    order: number;
+    /** 필수 필드 여부 (기본 `false`) */
+    is_required?: boolean;
+    /** 기본값 (서버는 임의 타입을 허용하므로 `unknown`) */
+    default_value?: unknown;
     description?: string;
     /**
      * 필드 레벨 암호화 활성화 여부.
@@ -251,26 +989,172 @@ interface CreateColumnRequest {
      * 서버에 SECRET_ENCRYPTION_KEY가 설정되어 있어야 합니다.
      */
     encrypted?: boolean;
+    /**
+     * @deprecated 서버가 무시합니다. 컬럼 순서는 서버가 자동 관리합니다.
+     */
+    order?: number;
+    /**
+     * @deprecated 서버가 해당 필드를 저장하지 않습니다.
+     */
+    validation_rule?: string;
 }
 interface UpdateColumnRequest {
-    name?: string;
     data_type?: DataType;
     is_required?: boolean;
-    default_value?: string;
-    validation_rule?: string;
-    order?: number;
+    default_value?: unknown;
     description?: string;
+    encrypted?: boolean;
+    /**
+     * @deprecated 서버가 컬럼 이름 변경을 지원하지 않습니다. 변경하려면
+     * 삭제 후 재생성하거나 data-server 의 rename 엔드포인트를 사용하세요.
+     */
+    name?: string;
+    /**
+     * @deprecated 서버가 무시합니다.
+     */
+    order?: number;
+    /**
+     * @deprecated 서버가 해당 필드를 저장하지 않습니다.
+     */
+    validation_rule?: string;
 }
+/**
+ * 서버(data-server `ent/schema/table.go` 의 `Table`) 가 반환하는 테이블 레코드.
+ * 필드 이름은 Go ent 모델과 일치합니다.
+ */
 interface TableSchema {
     id: string;
-    name: string;
-    description?: string;
-    columns: ColumnSchema[];
+    app_id: string;
+    /** 테이블 이름 (ent 필드: `title`) */
+    title: string;
+    /** 평면 스키마 맵. 컬럼 객체 배열로 변환하려면 `getColumns()` 사용. */
+    schema: TableSchemaDefinition;
+    /** 검증 스키마 (table-level). 설정되어 있으면 데이터 insert/update 시 평가됨. */
+    validation_schema?: ValidationSchema;
+    access_level: TableAccessLevel;
+    is_active: boolean;
     created_at: string;
-    updated_at?: string;
+    updated_at: string;
+}
+/**
+ * 컬럼 정의. 서버는 두 가지 형식 중 하나로 저장합니다:
+ * - 플랫: 타입 문자열만 (`'string'`, `'int'` 등)
+ * - 중첩: 타입 + 추가 속성 객체 (`{type, required, default, description, encrypted}`)
+ *
+ * 클라이언트에서 `createTable` 시에는 플랫 형태가 권장되며, 추가 속성은
+ * `createColumn` 을 사용하거나 중첩 객체로 직접 지정할 수 있습니다.
+ */
+type TableColumnDef = DataType | {
+    type: DataType;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    encrypted?: boolean;
+};
+/**
+ * 테이블 스키마 정의.
+ * 키는 컬럼 이름, 값은 타입 문자열 또는 중첩 컬럼 객체입니다.
+ * `$required` 는 특수 키로, 필수 컬럼 이름의 배열을 받습니다.
+ *
+ * @example
+ * ```ts
+ * // 플랫 형태
+ * { email: 'string', age: 'int', $required: ['email'] }
+ *
+ * // 중첩 형태 (필드별 옵션)
+ * { email: { type: 'string', required: true, encrypted: true } }
+ * ```
+ */
+interface TableSchemaDefinition {
+    /** 필수 컬럼 이름 목록 (서버 hook 이 `$required` 키로 해석) */
+    $required?: string[];
+    /** 컬럼명 → 컬럼 정의. `$required` 키는 예외적으로 `string[]` */
+    [columnName: string]: TableColumnDef | string[] | undefined;
+}
+/** 테이블 접근 수준 */
+type TableAccessLevel = 'Creator' | 'Public' | 'AppMember';
+/** 단일 필드의 검증 규칙 */
+interface ValidationSchemaField {
+    /** 데이터 타입 */
+    type: DataType;
+    /** 필수 여부 */
+    required?: boolean;
+    /** 기본값 */
+    default?: unknown;
+    /** 숫자 최소값 */
+    min?: number;
+    /** 숫자 최대값 */
+    max?: number;
+    /** 문자열 최소 길이 */
+    minLength?: number;
+    /** 문자열 최대 길이 */
+    maxLength?: number;
+    /** 정규식 패턴 (Go regexp 호환) */
+    pattern?: string;
+    /** 허용 값 목록 */
+    enum?: unknown[];
+    /** 배열 아이템 스키마 */
+    items?: ValidationSchemaField;
+    /** object 의 속성 스키마 */
+    properties?: Record<string, ValidationSchemaField>;
+    /** 수정 불가 (immutable) */
+    immutable?: boolean;
+    /** 유니크 제약 */
+    unique?: boolean;
+    /** 새니타이징 ('html', 'xss', 'trim') */
+    sanitize?: string;
+    /** 자동 계산 표현식 */
+    computed?: string;
+    /** 상태 전이 규칙: 현재상태 → 허용되는 다음 상태들 */
+    transitions?: Record<string, string[]>;
+}
+/** 상태 전이 규칙 (객체 단위 — 필드 + 전이 맵) */
+interface ValidationStateTransitions {
+    field: string;
+    transitions: Record<string, string[]>;
+}
+/**
+ * 테이블 검증 스키마 (table-level).
+ * 데이터 insert/update 시 자동으로 평가됩니다.
+ *
+ * @example
+ * ```ts
+ * {
+ *     fields: {
+ *         email: { type: 'string', pattern: '^.+@.+$', required: true },
+ *         age:   { type: 'int', min: 0, max: 150 }
+ *     },
+ *     required: ['email'],
+ *     immutable: ['email']
+ * }
+ * ```
+ */
+interface ValidationSchema {
+    fields: Record<string, ValidationSchemaField>;
+    required?: string[];
+    unique?: string[];
+    immutable?: string[];
+    computed?: Record<string, string>;
+    transitions?: Record<string, ValidationStateTransitions>;
 }
 interface CreateTableRequest {
+    /** 테이블 이름 (서버는 내부적으로 `title` 로 저장) */
     name: string;
+    /**
+     * 초기 컬럼 스키마 (선택).
+     * 생략하면 컬럼이 없는 빈 테이블로 생성되며, 이후 `addColumn()` 으로 추가할 수 있습니다.
+     */
+    schema?: TableSchemaDefinition;
+    /**
+     * 접근 수준 (선택, 기본값 `'Creator'`).
+     * - `Creator`: 테이블 생성자만 전체 권한
+     * - `Public`: 누구나 읽기/쓰기
+     * - `AppMember`: 앱 멤버만 읽기/쓰기
+     */
+    accessLevel?: TableAccessLevel;
+    /**
+     * @deprecated 서버에 저장되지 않습니다. 필드는 backward-compat 을 위해 남아있으며 SDK 가 서버로 전송하지 않습니다.
+     */
     description?: string;
 }
 interface DataItem {
@@ -285,9 +1169,21 @@ interface CreateDataRequest {
 interface UpdateDataRequest {
     data: Record<string, unknown>;
 }
+/**
+ * 테이블 데이터 조회 응답.
+ *
+ * 서버(data-server `internal_data_controller.go` 의 `FetchDataByTableGET`,
+ * `QueryDataByTable`) 가 반환하는 JSON 과 1:1 매핑합니다.
+ *
+ * 참고: `1.3.0` 이전 버전(`0.16.1` 기준)에서는 `datas` / `total_size` 로
+ * 선언돼 있었으나, 실제 서버 wire 포맷은 `data` / `total_count` 이므로 런타임에
+ * 속성 접근이 `undefined` 를 반환하는 결함이 있었습니다. `1.4.0` 에서 바로잡습니다.
+ */
 interface FetchDataResponse {
-    datas: DataItem[];
-    total_size: number;
+    /** 조회된 문서 배열 */
+    data: DataItem[];
+    /** 총 매칭 문서 수 */
+    total_count: number;
 }
 interface QueryOptions {
     limit?: number;
@@ -434,7 +1330,7 @@ interface PopulateOption {
     populate?: PopulateOption[];
 }
 type TriggerEvent = 'create' | 'update' | 'delete' | 'all';
-type TriggerHandlerType = 'function' | 'workflow' | 'webhook';
+type TriggerHandlerType = 'function' | 'workflow' | 'webhook' | 'inline';
 interface Trigger {
     id: string;
     app_id: string;
@@ -445,6 +1341,7 @@ interface Trigger {
     handler_type: TriggerHandlerType;
     handler_id?: string;
     handler_url?: string;
+    handler_action?: Record<string, unknown>;
     is_active: boolean;
     order: number;
     created_at: string;
@@ -457,6 +1354,7 @@ interface CreateTriggerRequest {
     handler_type: TriggerHandlerType;
     handler_id?: string;
     handler_url?: string;
+    handler_action?: Record<string, unknown>;
     condition?: Record<string, unknown>;
     is_active?: boolean;
     order?: number;
@@ -467,6 +1365,7 @@ interface UpdateTriggerRequest {
     handler_type?: TriggerHandlerType;
     handler_id?: string;
     handler_url?: string;
+    handler_action?: Record<string, unknown>;
     condition?: Record<string, unknown>;
     is_active?: boolean;
     order?: number;
@@ -588,6 +1487,31 @@ interface TransactionWrite {
         exists?: boolean;
     };
 }
+interface BatchOperationResult {
+    index: number;
+    success: boolean;
+    doc_id?: string;
+    error?: string;
+}
+interface BatchWriteResult {
+    success: boolean;
+    results: BatchOperationResult[];
+    total_count?: number;
+    success_count?: number;
+    failed_count?: number;
+}
+interface TransactionWriteResult {
+    index: number;
+    doc_id?: string;
+    success: boolean;
+}
+interface TransactionResult {
+    success: boolean;
+    transaction_id?: string;
+    reads?: Record<string, unknown>;
+    results?: TransactionWriteResult[];
+    error?: string;
+}
 interface TTLConfig {
     table_name: string;
     field: string;
@@ -679,7 +1603,11 @@ interface DatabaseRealtimeSubscription {
 }
 /** 데이터베이스 실시간 연결 옵션 */
 interface DatabaseRealtimeConnectOptions {
-    /** JWT 액세스 토큰 (필수) */
+    /**
+     * 액세스 토큰 (필수). 두 종류를 모두 지원:
+     *   - 앱 멤버(AppMember) JWT — 자기 앱의 테이블 구독
+     *   - cross-app OAuth access token — Provider 앱의 테이블 구독 (`database:read` scope 필요)
+     */
     accessToken: string;
     /** data-server URL (기본: baseUrl) */
     dataServerUrl?: string;
@@ -690,14 +1618,6 @@ interface DatabaseRealtimeConnectOptions {
     /** 디버그 로깅 (기본: false) */
     debug?: boolean;
 }
-/** 데이터베이스 실시간 프레즌스 상태 */
-interface DatabasePresenceState {
-    user_id: string;
-    status: 'online' | 'away' | 'offline';
-    last_seen: string;
-    device?: string;
-    metadata?: Record<string, unknown>;
-}
 interface CreateBackupRequest {
     /** 백업 이름 */
     name: string;
@@ -752,6 +1672,17 @@ interface ExportDataResponse {
     data?: Record<string, unknown>;
     schema?: Record<string, unknown>;
 }
+/**
+ * 데이터 가져오기 요청
+ * @example
+ * {
+ *   data: {
+ *     users:  { rows: [{ name: 'Alice', age: 30 }] },
+ *     orders: { rows: [{ user: 'Alice', amount: 1000 }] }
+ *   },
+ *   mode: 'merge'
+ * }
+ */
 interface ImportDataRequest {
     /** 가져올 데이터: { "테이블이름": { "rows": [{...}, ...] }, ... } */
     data: Record<string, {
@@ -872,37 +1803,109 @@ declare class DatabaseAPI {
     private activeSubscriptions;
     constructor(http: HttpClient);
     /**
-     * API Key 인증 시 /v1/public 접두사 반환
+     * Database 공개 API 접두사.
+     *
+     * 서버의 테이블/컬럼/데이터 CRUD 는 모두 `/v1/public/*` 경로에서만 제공되며
+     * (core-server → data-server 프록시), JWT 기반 `/v1/*` 경로는 존재하지 않습니다.
+     * 따라서 항상 `/v1/public` 을 사용합니다. 인증은 `X-Public-Key` 헤더에
+     * `publicKey` (`cb_pk_*`) 를 실어 서버가 검증합니다.
      */
     private getPublicPrefix;
     /**
      * 테이블 목록 조회
      */
-    getTables(databaseId: string): Promise<TableSchema[]>;
+    getTables(): Promise<TableSchema[]>;
     /**
-     * 테이블 생성
+     * 테이블 상세 조회
+     */
+    getTable(tableId: string): Promise<TableSchema>;
+    /**
+     * 테이블 생성.
+     *
+     * 서버 DTO (`{title, schema, access_level}`) 로 변환하여 전송합니다.
+     * `schema` 가 비어있으면 요청 본문에서 키 자체를 생략하여 빈 테이블을
+     * 생성합니다. (서버는 explicit 빈 맵을 거부)
+     *
+     * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+     * 생성된 테이블 메타데이터가 필요하면 이어서 `getTables()` 로 조회하세요.
+     */
+    createTable(data: CreateTableRequest): Promise<void>;
+    /**
+     * 테이블 수정.
+     *
+     * `name` 은 서버의 `title` 로, `accessLevel` 은 `access_level` 로 매핑됩니다.
      */
-    createTable(databaseId: string, data: CreateTableRequest): Promise<TableSchema>;
+    updateTable(tableId: string, data: Partial<CreateTableRequest>): Promise<void>;
     /**
      * 테이블 삭제
      */
-    deleteTable(databaseId: string, tableId: string): Promise<void>;
+    deleteTable(tableId: string): Promise<void>;
     /**
-     * 컬럼 목록 조회
+     * 테이블 검증 스키마 조회.
+     *
+     * 검증 스키마가 설정되어 있지 않으면 `null` 을 반환합니다.
+     * Public Key 인증으로 호출 가능 (조회 권한).
+     */
+    getValidationSchema(tableId: string): Promise<ValidationSchema | null>;
+    /**
+     * 테이블 검증 스키마 설정/교체.
+     *
+     * **권한**: 콘솔 (앱 소유자 JWT) 전용. Public Key 로는 설정 불가.
+     * SDK 에서는 `accessToken` 이 설정되어 있어야 하며, 콘솔에서 사용하는 패턴입니다.
+     *
+     * 빈 fields 는 거부됩니다. 검증 스키마를 제거하려면 `deleteValidationSchema` 사용.
+     *
+     * @example
+     * ```ts
+     * await cb.database.setValidationSchema(tableId, {
+     *     fields: {
+     *         email: { type: 'string', pattern: '^.+@.+$', required: true },
+     *         age: { type: 'int', min: 0, max: 150 }
+     *     },
+     *     required: ['email'],
+     *     immutable: ['email']
+     * })
+     * ```
+     */
+    setValidationSchema(tableId: string, schema: ValidationSchema): Promise<void>;
+    /**
+     * 테이블 검증 스키마 제거 (schemaless 모드로 복귀).
+     *
+     * **권한**: 콘솔 (앱 소유자 JWT) 전용.
+     */
+    deleteValidationSchema(tableId: string): Promise<void>;
+    /**
+     * appId 가 설정되어 있어야 콘솔 경로를 호출할 수 있습니다 (validation_schema set/delete).
+     */
+    private requireAppId;
+    /**
+     * 컬럼 목록 조회 (`Table.schema` 맵을 컬럼 객체 배열로 변환).
+     *
+     * 서버는 컬럼을 다음 두 가지 중 하나로 저장합니다:
+     * - 플랫: `"email": "string"` (추가 속성이 없는 경우)
+     * - 중첩: `"email": { "type": "string", "required": true, ... }` (추가 속성이 있는 경우)
+     *
+     * `$required` 키는 별도 배열로 필수 컬럼을 지정할 수 있으며, 중첩 객체의
+     * `required: true` 와 병합되어 판정됩니다.
      */
     getColumns(tableId: string): Promise<ColumnSchema[]>;
     /**
-     * 컬럼 생성
+     * 컬럼 생성.
+     *
+     * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+     * 생성 결과 컬럼을 얻으려면 이어서 `getColumns(tableId)` 로 조회하세요.
      */
-    createColumn(tableId: string, data: CreateColumnRequest): Promise<ColumnSchema>;
+    createColumn(tableId: string, data: CreateColumnRequest): Promise<void>;
     /**
-     * 컬럼 수정
+     * 컬럼 수정.
+     *
+     * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
      */
-    updateColumn(tableId: string, columnId: string, data: UpdateColumnRequest): Promise<ColumnSchema>;
+    updateColumn(tableId: string, columnName: string, data: UpdateColumnRequest): Promise<void>;
     /**
      * 컬럼 삭제
      */
-    deleteColumn(tableId: string, columnId: string): Promise<void>;
+    deleteColumn(tableId: string, columnName: string): Promise<void>;
     /**
      * 데이터 조회 (페이지네이션)
      */
@@ -916,9 +1919,19 @@ declare class DatabaseAPI {
      */
     getDataById(tableId: string, dataId: string): Promise<DataItem>;
     /**
-     * 데이터 생성
+     * 데이터 생성.
+     *
+     * `tableIdOrName` 은 테이블 UUID 또는 이름. UUID 형식이면 기존 경로
+     * (`/tables/:tableId/data`), 그렇지 않으면 이름 기반 경로
+     * (`/tables/name/:tableName/data`) 를 사용합니다.
+     *
+     * `options.autoCreate: true` 시 테이블이 없으면 빈 schemaless 테이블을
+     * 자동으로 생성한 뒤 insert. opt-in 이며 프로토타입/AI 자동화 워크플로에
+     * 권장합니다. production 앱은 명시적 `createTable` 호출 권장.
      */
-    createData(tableId: string, data: CreateDataRequest): Promise<DataItem>;
+    createData(tableIdOrName: string, data: CreateDataRequest, options?: {
+        autoCreate?: boolean;
+    }): Promise<DataItem>;
     /**
      * 데이터 수정 (부분 업데이트)
      * 제공된 필드만 수정되고, 기존 필드는 유지됩니다.
@@ -959,16 +1972,18 @@ declare class DatabaseAPI {
     }): Promise<GeoResponse>;
     /**
      * 배치 쓰기 (여러 테이블 다중 문서 원자적 처리)
+     *
+     * 서버는 HTTP 200 + `success:false` + 개별 op `error` 로 부분 실패를 표현한다.
+     * SDK 는 호출자가 silent success 로 오해하지 않도록 첫 실패 op 의 메시지로 throw 한다.
      */
-    batch(operations: BatchOperation[]): Promise<{
-        results: Record<string, unknown>[];
-    }>;
+    batch(operations: BatchOperation[]): Promise<BatchWriteResult>;
     /**
      * 트랜잭션 실행 (읽기 → 쓰기 ACID)
+     *
+     * 서버는 부분 실패가 없는 ACID 트랜잭션을 보장하지만, 검증/RLS/충돌은
+     * `success:false` + `error` 로 알린다. SDK 는 silent success 회귀 방지 차원에서 throw.
      */
-    transaction(reads: TransactionRead[], writes: TransactionWrite[]): Promise<{
-        results: Record<string, unknown>;
-    }>;
+    transaction(reads: TransactionRead[], writes: TransactionWrite[]): Promise<TransactionResult>;
     /**
      * 데이터 조회 시 릴레이션 로딩 (JOIN)
      */
@@ -1014,17 +2029,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>;
     /**
      * 트리거 목록 조회
      */
@@ -1087,14 +2108,26 @@ declare class DatabaseAPI {
      * 데이터베이스 실시간 연결
      * data-server의 WebSocket에 연결하여 데이터 변경을 실시간으로 수신합니다.
      *
+     * `accessToken` 은 두 종류를 모두 받습니다:
+     *   - 앱 멤버(AppMember) JWT — 자기 앱의 테이블을 구독
+     *   - cross-app OAuth access token — Provider 앱이 `database:read` scope 를 노출했을 때,
+     *     Consumer 가 Provider 앱의 테이블을 구독 (구독 대상 앱은 토큰 `aud` 로 결정되므로
+     *     Provider 의 publicKey 는 불필요). RLS 는 토큰 `end_user_id` 를 subject 로 평가합니다.
+     *
      * @example
      * ```typescript
-     * // 연결
+     * // 자기 앱 테이블 구독 (AppMember JWT)
      * cb.database.connectRealtime({
      *     accessToken: 'your-jwt-token',
      *     dataServerUrl: 'https://data.connectbase.world'
      * })
      *
+     * // cross-app: Provider 앱의 테이블 구독 (OAuth access token)
+     * cb.database.connectRealtime({
+     *     accessToken: oauthAccessToken,
+     *     dataServerUrl: 'https://data.connectbase.world'
+     * })
+     *
      * // 테이블 구독
      * const sub = cb.database.subscribe('users', {
      *     onSnapshot: (docs, info) => {
@@ -1129,14 +2162,6 @@ declare class DatabaseAPI {
      * @returns 구독 해제 가능한 객체
      */
     subscribe(tableId: string, handlers: DatabaseRealtimeHandlers, options?: DatabaseSubscribeOptions): DatabaseRealtimeSubscription;
-    /**
-     * 프레즌스 상태 설정
-     */
-    setPresence(status: string, device?: string, metadata?: Record<string, unknown>): void;
-    /**
-     * 프레즌스 구독 (다른 사용자의 온라인 상태 감시)
-     */
-    subscribePresence(userIds: string[], onPresence: (states: Record<string, DatabasePresenceState>) => void): void;
     /**
      * 실시간 연결 상태 확인
      */
@@ -1366,10 +2391,28 @@ declare class StorageAPI {
      * API Key 인증 시 /v1/public 접두사 반환
      */
     private getPublicPrefix;
+    /**
+     * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
+     * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
+     * 타임아웃과 외부 signal 을 모두 지원한다.
+     */
+    private uploadToPresigned;
     /**
      * 파일 목록 조회
+     *
+     * @param storageId - 파일 스토리지 ID
+     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     *
+     * @example
+     * ```ts
+     * // 루트 폴더의 파일 목록
+     * const files = await cb.storage.getFiles('storage-id')
+     *
+     * // 특정 폴더의 하위 파일 목록
+     * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
+     * ```
      */
-    getFiles(storageId: string): Promise<FileItem[]>;
+    getFiles(storageId: string, parentId?: string): Promise<FileItem[]>;
     /**
      * 파일 업로드 (Presigned URL 방식)
      *
@@ -1397,10 +2440,14 @@ declare class StorageAPI {
     deleteFile(storageId: string, fileId: string): Promise<void>;
     /**
      * 파일/폴더 이동
+     *
+     * Public Key 인증만으로는 이 엔드포인트가 노출되지 않습니다. JWT(콘솔 토큰)가 필요합니다.
      */
     moveFile(storageId: string, fileId: string, data: MoveFileRequest): Promise<void>;
     /**
      * 파일/폴더 이름 변경
+     *
+     * Public Key 인증만으로는 이 엔드포인트가 노출되지 않습니다. JWT(콘솔 토큰)가 필요합니다.
      */
     renameFile(storageId: string, fileId: string, data: RenameFileRequest): Promise<RenameFileResponse>;
     /**
@@ -1524,15 +2571,15 @@ declare class StorageAPI {
 }
 
 /**
- * API Key 관련 타입 정의
+ * Public Key 관련 타입 정의
  */
 /**
- * API Key 아이템
+ * Public Key 아이템
  */
-interface ApiKeyItem {
-    /** API Key ID */
+interface PublicKeyItem {
+    /** Public Key ID */
     id: string;
-    /** API Key 이름 */
+    /** Public Key 이름 */
     name: string;
     /** 키 앞 12자리 (표시용) */
     key_prefix: string;
@@ -1546,21 +2593,21 @@ interface ApiKeyItem {
     created_at: string;
 }
 /**
- * API Key 생성 요청
+ * Public Key 생성 요청
  */
-interface CreateApiKeyRequest {
-    /** API Key 이름 (예: Production, Development) */
+interface CreatePublicKeyRequest {
+    /** Public Key 이름 (예: Production, Development) */
     name: string;
     /** 만료일 (옵션) */
     expires_at?: string;
 }
 /**
- * API Key 생성 응답 (전체 키는 이때만 반환됨)
+ * Public Key 생성 응답 (전체 키는 이때만 반환됨)
  */
-interface CreateApiKeyResponse {
-    /** API Key ID */
+interface CreatePublicKeyResponse {
+    /** Public Key ID */
     id: string;
-    /** API Key 이름 */
+    /** Public Key 이름 */
     name: string;
     /** 전체 키 값 (생성 시에만 반환, 안전하게 보관 필요) */
     key: string;
@@ -1574,24 +2621,24 @@ interface CreateApiKeyResponse {
     created_at: string;
 }
 /**
- * API Key 목록 조회 응답
+ * Public Key 목록 조회 응답
  */
-interface FetchApiKeysResponse {
-    api_keys: ApiKeyItem[];
+interface FetchPublicKeysResponse {
+    public_keys: PublicKeyItem[];
 }
 /**
- * API Key 수정 요청
+ * Public Key 수정 요청
  */
-interface UpdateApiKeyRequest {
-    /** API Key 이름 변경 */
+interface UpdatePublicKeyRequest {
+    /** Public Key 이름 변경 */
     name?: string;
     /** 활성화/비활성화 */
     is_active?: boolean;
 }
 /**
- * API Key 수정 응답
+ * Public Key 수정 응답
  */
-interface UpdateApiKeyResponse {
+interface UpdatePublicKeyResponse {
     id: string;
     name: string;
     key_prefix: string;
@@ -1601,55 +2648,55 @@ interface UpdateApiKeyResponse {
 }
 
 /**
- * API Key 관리 API
+ * Public Key 관리 API
  *
  * @example
  * ```typescript
- * // API Key 목록 조회
- * const keys = await cb.apiKey.getApiKeys('app-id')
+ * // Public Key 목록 조회
+ * const keys = await cb.publicKey.getPublicKeys('app-id')
  *
- * // 새 API Key 생성
- * const newKey = await cb.apiKey.createApiKey('app-id', { name: 'Production' })
+ * // 새 Public Key 생성
+ * const newKey = await cb.publicKey.createPublicKey('app-id', { name: 'Production' })
  * console.log(newKey.key) // 전체 키 (이때만 볼 수 있음!)
  *
- * // API Key 비활성화
- * await cb.apiKey.updateApiKey('app-id', 'key-id', { is_active: false })
+ * // Public Key 비활성화
+ * await cb.publicKey.updatePublicKey('app-id', 'key-id', { is_active: false })
  *
- * // API Key 삭제
- * await cb.apiKey.deleteApiKey('app-id', 'key-id')
+ * // Public Key 삭제
+ * await cb.publicKey.deletePublicKey('app-id', 'key-id')
  * ```
  */
-declare class ApiKeyAPI {
+declare class PublicKeyAPI {
     private http;
     constructor(http: HttpClient);
     /**
-     * 앱의 API Key 목록을 조회합니다
+     * 앱의 Public Key 목록을 조회합니다
      * @param appId 앱 ID
      */
-    getApiKeys(appId: string): Promise<FetchApiKeysResponse>;
+    getPublicKeys(appId: string): Promise<FetchPublicKeysResponse>;
     /**
-     * 새 API Key를 생성합니다
+     * 새 Public Key 를 생성합니다
      *
      * **중요**: 반환되는 `key` 값은 이 응답에서만 볼 수 있습니다.
      * 안전한 곳에 저장하세요.
      *
      * @param appId 앱 ID
-     * @param data 생성할 API Key 정보
+     * @param data 생성할 Public Key 정보
      */
-    createApiKey(appId: string, data: CreateApiKeyRequest): Promise<CreateApiKeyResponse>;
+    createPublicKey(appId: string, data: CreatePublicKeyRequest): Promise<CreatePublicKeyResponse>;
     /**
-     * API Key를 수정합니다 (이름 변경, 활성화/비활성화)
+     * Public Key 를 수정합니다 (이름 변경, 활성화/비활성화)
      * @param appId 앱 ID
-     * @param keyId API Key ID
+     * @param keyId Public Key ID
      * @param data 수정할 정보
      */
-    updateApiKey(appId: string, keyId: string, data: UpdateApiKeyRequest): Promise<UpdateApiKeyResponse>;
+    updatePublicKey(appId: string, keyId: string, data: UpdatePublicKeyRequest): Promise<UpdatePublicKeyResponse>;
     /**
-     * API Key를 삭제합니다
+     * Public Key 를 삭제합니다
      * @param appId 앱 ID
-     * @param keyId API Key ID
+     * @param keyId Public Key ID
      */
-    deleteApiKey(appId: string, keyId: string): Promise<void>;
+    deletePublicKey(appId: string, keyId: string): Promise<void>;
 }
 
 /**
@@ -1710,6 +2757,36 @@ declare class FunctionsAPI {
      * ```
      */
     invoke(functionId: string, payload?: Record<string, unknown>, timeout?: number): Promise<InvokeFunctionResponse>;
+    /**
+     * cross-app OAuth 액세스 토큰으로 다른 앱(Provider)의 함수를 실행합니다.
+     *
+     * Provider 앱이 OAuth Provider 로 `function:invoke` scope 를 노출하고, Consumer 앱이
+     * cross-app OAuth 로 발급받은 access token 으로 Provider 의 함수를 호출하는 경로입니다.
+     * 호출자 신원은 서버가 토큰에서 추출해 함수 런타임의 `ctx.memberId`(end-user) /
+     * `ctx.callerAppId`(Consumer 앱) 로 전달하므로, 함수 핸들러가 호출자별 로직을 구현할 수 있습니다.
+     *
+     * 일반 `invoke()` 와 달리 SDK 클라이언트의 publicKey/멤버 토큰이 아니라 전달된
+     * `accessToken` 만 `Authorization: Bearer` 로 사용합니다.
+     *
+     * @param providerAppId - 함수를 소유한 Provider 앱 ID (토큰 `aud` 의 `app:<id>` 와 일치해야 함)
+     * @param functionId - 실행할 함수 ID
+     * @param accessToken - cross-app OAuth access token
+     * @param payload - 함수에 전달할 데이터 (선택)
+     * @param timeout - 실행 타임아웃 (초, 선택)
+     * @returns 함수 실행 결과
+     *
+     * @example
+     * ```typescript
+     * // Consumer 앱이 Provider(ai-tool)의 함수를 호출
+     * const result = await cb.functions.invokeCrossApp(
+     *     'provider-app-id',
+     *     'models-generate-image',
+     *     oauthAccessToken,
+     *     { prompt: 'a cat' }
+     * )
+     * ```
+     */
+    invokeCrossApp(providerAppId: string, functionId: string, accessToken: string, payload?: Record<string, unknown>, timeout?: number): Promise<InvokeFunctionResponse>;
     /**
      * 서버리스 함수 실행 (비동기 래퍼)
      * 결과만 반환하고 메타데이터는 제외
@@ -1725,6 +2802,25 @@ declare class FunctionsAPI {
      * ```
      */
     call<T = unknown>(functionId: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * 함수의 raw HTTP webhook 수신용 공개 URL 을 반환합니다.
+     *
+     * 함수가 `http_trigger_enabled=true` 로 생성/수정되어야 동작합니다.
+     * 이 URL 을 외부 SaaS (Discord Interactions, Stripe Webhooks, GitHub Webhooks,
+     * Slack Events 등) 에 등록하면 raw HTTP 요청이 함수 핸들러에 그대로 전달됩니다.
+     *
+     * - body 는 wrap 없이 raw bytes 그대로 (Ed25519/HMAC 서명 검증 호환)
+     * - 모든 헤더 forward (X-Signature-*, Stripe-Signature 등)
+     * - 함수가 `{statusCode, headers, body}` 를 반환하면 그대로 HTTP 응답에 매핑
+     *
+     * @example
+     * ```typescript
+     * // Discord 봇 endpoint 등록용 URL
+     * const url = cb.functions.getWebhookURL('function-id')
+     * // → https://api.connectbase.world/v1/public/functions/<id>/webhook
+     * ```
+     */
+    getWebhookURL(functionId: string): string;
 }
 
 /**
@@ -1805,22 +2901,47 @@ interface ClientMessage {
 /** 서버 -> 클라이언트 메시지 */
 interface ServerMessage<T = unknown> {
     category?: string;
-    event: 'connected' | 'subscribed' | 'unsubscribed' | 'message' | 'sent' | 'result' | 'error' | 'pong' | 'history' | 'stream_token' | 'stream_done' | 'stream_error' | 'read_receipt' | 'presence' | 'presence_status' | 'typing';
+    event: 'connected' | 'subscribed' | 'unsubscribed' | 'message' | 'sent' | 'result' | 'error' | 'pong' | 'history' | 'stream_token' | 'stream_done' | 'stream_error' | 'stream_tool_call' | 'stream_tool_result' | 'read_receipt' | 'presence' | 'presence_status' | 'typing';
     data?: T;
     request_id?: string;
     error?: string;
     timestamp: number;
 }
-/** AI 스트리밍 메시지 */
+/** AI 스트리밍 메시지의 단일 텍스트 파트 (멀티모달 content array 항목). OpenAI Vision spec. */
+interface StreamTextPart {
+    type: 'text';
+    text: string;
+}
+/** AI 스트리밍 메시지의 이미지 파트. URL 은 https://... 또는 data:image/...;base64,... */
+interface StreamImageURLPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        /** OpenAI 전용 힌트 ('auto' | 'low' | 'high'). 다른 provider 는 무시. */
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/** AI 스트리밍 메시지의 단일 content 파트. */
+type StreamContentPart = StreamTextPart | StreamImageURLPart;
+/**
+ * AI 스트리밍 메시지.
+ *
+ * content 는 string (단일 텍스트) 또는 StreamContentPart[] (멀티모달) 를 받습니다.
+ * 멀티모달 형식은 OpenAI Vision spec (https://platform.openai.com/docs/guides/vision)
+ * 을 따르며, 서버가 각 provider 의 wire format 으로 변환:
+ *   - openai / openai_compatible (vLLM 등): content array 그대로 passthrough
+ *   - claude: data URI → base64 source, https URL → url source 의 image content block
+ *   - gemini: image URL fetch → base64 inline_data (Gemini API 가 외부 URL fetch 미지원)
+ */
 interface StreamMessage {
     role: 'user' | 'assistant' | 'system';
-    content: string;
+    content: string | StreamContentPart[];
 }
 /** AI 스트리밍 요청 옵션 */
 interface StreamOptions {
-    /** AI 프로바이더 (기본: gemini) */
-    provider?: 'gemini' | 'openai' | 'claude';
-    /** 모델명 (기본: gemini-2.5-flash) */
+    /** AI 프로바이더 (앱 설정의 프로바이더 사용. override 시 지정) */
+    provider?: 'gemini' | 'openai' | 'claude' | 'ollama' | 'lm_studio' | 'openai_compatible';
+    /** 모델명 (앱 설정의 모델을 override (선택적)) */
     model?: string;
     /** 시스템 프롬프트 */
     system?: string;
@@ -1832,6 +2953,8 @@ interface StreamOptions {
     sessionId?: string;
     /** 사용자 정의 메타데이터 */
     metadata?: Record<string, unknown>;
+    /** MCP 그룹 슬러그 (AI Agent 모드 — 등록된 MCP 서버의 도구를 AI에 제공) */
+    mcpGroup?: string;
 }
 /** AI 스트리밍 토큰 콜백 */
 type StreamTokenCallback = (token: string, index: number) => void;
@@ -1847,11 +2970,19 @@ interface StreamDoneData {
 type StreamDoneCallback = (result: StreamDoneData) => void;
 /** AI 스트리밍 에러 콜백 */
 type StreamErrorCallback = (error: Error) => void;
+/** AI 도구 호출 콜백 */
+type StreamToolCallCallback = (toolName: string, args: Record<string, unknown>, index: number) => void;
+/** AI 도구 실행 완료 콜백 */
+type StreamToolResultCallback = (toolName: string, success: boolean, durationMs: number, index: number) => void;
 /** AI 스트리밍 핸들러 */
 interface StreamHandlers {
     onToken?: StreamTokenCallback;
     onDone?: StreamDoneCallback;
     onError?: StreamErrorCallback;
+    /** MCP 도구 호출 시 콜백 (AI Agent 모드) */
+    onToolCall?: StreamToolCallCallback;
+    /** MCP 도구 실행 완료 시 콜백 (AI Agent 모드) */
+    onToolResult?: StreamToolResultCallback;
 }
 /** AI 스트리밍 세션 */
 interface StreamSession {
@@ -2211,6 +3342,12 @@ declare class RealtimeAPI {
     onReadReceipt(category: string, handler: ReadReceiptHandler): () => void;
     private doConnect;
     private log;
+    /**
+     * 에러 로그. `options.debug` 가 true 일 때만 console 에 출력.
+     * 운영 환경에서는 소비자 애플리케이션의 `ConnectBase({ onError })` 또는
+     * `cb.errorTracker` 로 전달하는 것을 권장하므로 SDK 자체 console 출력은 opt-in.
+     */
+    private logError;
     private handleServerMessage;
     private handleDisconnect;
     /**
@@ -2571,7 +3708,7 @@ declare class ErrorTrackerAPI {
 /**
  * OAuth 프로바이더 타입
  */
-type OAuthProvider = 'google' | 'kakao' | 'naver' | 'github' | 'discord' | 'apple';
+type OAuthProvider = 'google' | 'kakao' | 'naver' | 'apple' | 'github' | 'discord';
 /**
  * 활성화된 OAuth 프로바이더 정보
  */
@@ -2593,12 +3730,17 @@ interface GetAuthorizationURLResponse {
 }
 /**
  * OAuth 콜백 응답
+ *
+ * `email` 은 1.10 부터 추가된 선택적 필드. Apple private relay 또는 이메일 권한 미동의
+ * 시 빈 문자열 / undefined 일 수 있다. 값이 있으면 첫 로그인 시점에 이메일을 확보할 수 있어
+ * 별도 `getMember()` 호출이 불필요하다.
  */
 interface OAuthCallbackResponse {
     member_id: string;
     access_token: string;
     refresh_token: string;
     is_new_member: boolean;
+    email?: string;
 }
 
 /**
@@ -2636,9 +3778,10 @@ declare class OAuthAPI {
     getEnabledProviders(): Promise<EnabledProvidersResponse>;
     /**
      * 소셜 로그인 (리다이렉트 방식) - 권장
-     * Google Cloud Console에 별도로 redirect_uri를 등록할 필요가 없습니다.
-     * OAuth 완료 후 지정한 콜백 URL로 토큰과 함께 리다이렉트됩니다.
-     * 모든 배포 환경에서 안정적으로 동작합니다.
+     *
+     * 기존 회원만 로그인 (`intent=signin` 명시). 이 앱에서 처음인 사용자는 콜백에서
+     * `error=account_not_found` 를 받아 가입 안내 UX 로 분기해야 한다. 신규 가입까지 한 번에
+     * 처리하려면 [signUp] 을 사용한다.
      *
      * @param provider - OAuth 프로바이더 (google, naver, github, discord)
      * @param callbackUrl - OAuth 완료 후 리다이렉트될 앱의 URL
@@ -2646,27 +3789,30 @@ declare class OAuthAPI {
      *
      * @example
      * ```typescript
-     * // 로그인 버튼 클릭 시
+     * // "로그인" 버튼 클릭 시
      * await cb.oauth.signIn('google', 'https://myapp.com/oauth/callback')
-     * // Google 로그인 후 https://myapp.com/oauth/callback?access_token=...&refresh_token=... 로 리다이렉트됨
      * ```
      *
      * @example
      * ```typescript
      * // callback 페이지에서
-     * const result = cb.oauth.getCallbackResult()
-     * if (result) {
-     *     if (result.error) {
-     *         console.error('로그인 실패:', result.error)
-     *     } else {
-     *         console.log('로그인 성공:', result.member_id)
-     *         // 메인 페이지로 이동
-     *         window.location.href = '/'
-     *     }
+     * const result = await cb.oauth.getCallbackResult()
+     * if (result?.error === 'account_not_found') {
+     *     // 가입되지 않은 사용자 — 회원가입 화면으로 안내
+     *     window.location.href = '/signup'
      * }
      * ```
      */
     signIn(provider: OAuthProvider, callbackUrl: string, state?: string): Promise<void>;
+    /**
+     * 소셜 회원가입 (리다이렉트 방식) — 사용자가 명시적으로 가입 의사를 표시한 경우에만 호출.
+     *
+     * 기존 회원이면 그대로 로그인 (idempotent). 없으면 신규 AppMember 생성.
+     * "로그인" 버튼에는 [signIn] 을 쓰고, "회원가입" 버튼에서만 이 메서드를 호출해야 silent
+     * auto-signup 회귀를 방지할 수 있다.
+     */
+    signUp(provider: OAuthProvider, callbackUrl: string, state?: string): Promise<void>;
+    private startCentralOAuth;
     /**
      * 소셜 로그인 (팝업 방식)
      * 팝업 창에서 소셜 로그인을 처리하고 결과를 Promise로 반환합니다.
@@ -2691,36 +3837,72 @@ declare class OAuthAPI {
      * const result = await cb.oauth.signInWithPopup('google', 'https://myapp.com/oauth/callback')
      * ```
      */
-    signInWithPopup(provider: OAuthProvider, callbackUrl?: string): Promise<OAuthCallbackResponse>;
+    signInWithPopup(provider: OAuthProvider, callbackUrl?: string, options?: {
+        intent?: 'signin' | 'signup';
+    }): Promise<OAuthCallbackResponse>;
     /**
      * 콜백 URL에서 OAuth 결과 추출
      * 중앙 콜백 방식에서 리다이렉트 후 URL 파라미터에서 결과를 추출합니다.
      * 토큰이 있으면 자동으로 저장됩니다.
      *
+     * 본 메서드는 `Promise` 를 반환한다. 토큰 저장 직후 `cb_member_refresh_token`
+     * cookie 부트스트랩(`/v1/auth/re-issue` 1회)을 *await* 하기 위함이다. 표준 예제
+     * 코드는 결과를 await 한 다음 `window.location.href='/'` 로 이동하므로, cookie 가
+     * 브라우저에 안전하게 저장된 뒤 페이지가 전환된다.
+     *
+     * 이전(3.22.x) 의 fire-and-forget 부트스트랩은 모바일/느린 네트워크에서 navigation
+     * 이 fetch 보다 먼저 발화해 cookie 가 발급되지 않고, 새 페이지 진입 시 cookie
+     * 없는 상태로 `getMe()` 가 401 으로 떨어지는 회귀가 있었다 (platform-issue
+     * 019e638d, 2026-05-26).
+     *
      * @returns OAuth 결과 (토큰, member_id 등) 또는 null
      *
      * @example
      * ```typescript
      * // callback 페이지에서
-     * const result = cb.oauth.getCallbackResult()
+     * const result = await cb.oauth.getCallbackResult()
      * if (result) {
      *     if (result.error) {
      *         alert('로그인 실패: ' + result.error)
      *     } else {
-     *         console.log('로그인 성공:', result.member_id)
      *         window.location.href = '/'
      *     }
      * }
      * ```
      */
-    getCallbackResult(): {
+    getCallbackResult(): Promise<{
         access_token?: string;
         refresh_token?: string;
         member_id?: string;
         is_new_member?: boolean;
+        email?: string;
         state?: string;
         error?: string;
-    } | null;
+    } | null>;
+    /**
+     * 콜백 URL 에서 1회용 `code` 를 토큰으로 교환합니다 (`OAUTH_CODE_ONLY` 서버 모드용).
+     *
+     * 서버가 `OAUTH_CODE_ONLY=true` 모드면 리다이렉트 URL 에 토큰 대신 `code` 만 포함됩니다.
+     * 이 메서드는 code 를 `POST /v1/auth/oauth/exchange` 로 교환하고 토큰을 자동 저장합니다.
+     *
+     * 권장 호출 순서:
+     *   1) `cb.oauth.exchangeCodeFromCallback()` 먼저 — code-only 모드면 성공
+     *   2) null 반환 시 `cb.oauth.getCallbackResult()` 폴백 (legacy 토큰-in-URL 모드)
+     *
+     * @example
+     * ```typescript
+     * const result = await cb.oauth.exchangeCodeFromCallback()
+     *   ?? cb.oauth.getCallbackResult()
+     * ```
+     */
+    exchangeCodeFromCallback(): Promise<{
+        access_token: string;
+        refresh_token: string;
+        member_id: string;
+        is_new_member: boolean;
+        email?: string;
+        state?: string;
+    } | null>;
 }
 
 type PaymentProvider = 'toss' | 'stripe';
@@ -2747,6 +3929,25 @@ interface PreparePaymentResponse {
     stripe_client_secret?: string;
     stripe_publishable_key?: string;
 }
+interface CreateCheckoutSessionRequest {
+    amount: number;
+    currency: string;
+    product_name: string;
+    success_url: string;
+    cancel_url: string;
+    order_id?: string;
+    customer_email?: string;
+    customer_name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateCheckoutSessionResponse {
+    payment_id: string;
+    order_id: string;
+    amount: number;
+    currency: string;
+    session_id: string;
+    session_url: string;
+}
 interface ConfirmPaymentRequest {
     payment_key: string;
     order_id: string;
@@ -2814,35 +4015,61 @@ declare class PaymentAPI {
      *
      * @example
      * ```typescript
-     * const prepareResult = await client.payment.prepare({
+     * const result = await cb.payment.prepare({
      *     amount: 10000,
-     *     order_name: '테스트 상품',
+     *     order_name: '프리미엄 1개월',
      *     customer_email: 'test@example.com',
      *     customer_name: '홍길동'
      * })
      *
-     * // 토스 결제 위젯 초기화
-     * const tossPayments = TossPayments(prepareResult.toss_client_key)
-     * await tossPayments.requestPayment('카드', {
-     *     amount: prepareResult.amount,
-     *     orderId: prepareResult.order_id,
-     *     orderName: prepareResult.order_name,
-     *     customerKey: prepareResult.customer_key,
-     *     successUrl: prepareResult.success_url,
-     *     failUrl: prepareResult.fail_url
-     * })
+     * // Toss V2 결제 플로우
+     * if (result.payment_provider === 'toss') {
+     *   const tossPayments = TossPayments(result.toss_client_key)
+     *   const payment = tossPayments.payment({ customerKey: result.customer_key })
+     *   await payment.requestPayment({
+     *     method: 'CARD',
+     *     amount: { currency: 'KRW', value: result.amount },
+     *     orderId: result.order_id,
+     *     orderName: result.order_name,
+     *     successUrl: result.success_url,
+     *     failUrl: result.fail_url,
+     *   })
+     * }
      *
-     * // Stripe 결제 플로우:
-     * // const result = await client.payment.prepare({ amount: 1000, order_name: 'Product' })
-     * // if (result.payment_provider === 'stripe') {
-     * //   const stripe = await loadStripe(result.stripe_publishable_key)
-     * //   const elements = stripe.elements({ clientSecret: result.stripe_client_secret })
-     * //   // Mount PaymentElement, then:
-     * //   // stripe.confirmPayment({ elements, redirect: 'if_required' })
-     * // }
+     * // Stripe 결제 플로우
+     * if (result.payment_provider === 'stripe') {
+     *   const stripe = await loadStripe(result.stripe_publishable_key)
+     *   const elements = stripe.elements({ clientSecret: result.stripe_client_secret })
+     *   // Mount PaymentElement, then:
+     *   // stripe.confirmPayment({ elements, redirect: 'if_required' })
+     * }
      * ```
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
+    /**
+     * Stripe-hosted 결제 페이지 세션 생성 (client_secret 미노출 플로우).
+     *
+     * Elements 플로우(`prepare`) 대신 Stripe-hosted Checkout 페이지로 리다이렉트하고 싶을 때 사용.
+     * 응답에 `session_url` 이 포함되며, 브라우저를 해당 URL 로 이동시키면 Stripe 가 카드 입력·결제를 처리한 뒤
+     * `success_url` / `cancel_url` 로 복귀한다. `client_secret` 은 서버·클라이언트 어디에도 노출되지 않는다.
+     *
+     * @param data - 결제 세션 정보 (금액, 통화, 상품명, success/cancel URL 등)
+     * @returns session_id, session_url (redirect 대상)
+     *
+     * @example
+     * ```typescript
+     * const sess = await client.payment.createCheckoutSession({
+     *   amount: 1000,
+     *   currency: 'USD',
+     *   product_name: 'Premium Subscription',
+     *   success_url: 'https://app.example.com/success?session_id={CHECKOUT_SESSION_ID}',
+     *   cancel_url: 'https://app.example.com/cancel',
+     *   customer_email: 'user@example.com',
+     * })
+     * window.location.href = sess.session_url
+     * ```
+     */
+    createCheckoutSession(data: CreateCheckoutSessionRequest): Promise<CreateCheckoutSessionResponse>;
     /**
      * 결제 승인
      * 토스에서 결제 완료 후 콜백으로 받은 정보로 결제를 최종 승인합니다.
@@ -3397,7 +4624,7 @@ declare class SubscriptionAPI {
      *     order_name: '추가 결제'
      * })
      *
-     * if (result.status === 'DONE') {
+     * if (result.status === 'done') {
      *     console.log('결제 완료!')
      * }
      * ```
@@ -3461,6 +4688,35 @@ interface WebPushSubscription {
     };
 }
 
+/**
+ * `cb.push.sendToMembers` 페이로드. 백엔드 `dto.SendPushRequest` 의 멤버 발송 케이스
+ * 에 매핑되며, target_type / target_member_ids 는 SDK 가 자동 채운다.
+ */
+interface SendToMembersPayload {
+    title: string;
+    body: string;
+    imageUrl?: string;
+    data?: Record<string, unknown>;
+    /** 'ios' | 'android' | 'web' 중 선택. 빈 배열/미지정 시 전체 플랫폼 발송. */
+    platforms?: Array<'ios' | 'android' | 'web'>;
+    /** TTL(초). 기본 86400 (24h). */
+    ttlSeconds?: number;
+    priority?: 'normal' | 'high';
+    clickAction?: string;
+    /** ISO8601 형식 예약 발송 시각. 미지정 시 즉시 발송. */
+    scheduledAt?: string;
+}
+/**
+ * 발송 결과. 백엔드 `dto.SendResultResponse` 와 1:1 매핑.
+ */
+interface SendPushResult {
+    message_id: string;
+    total_target: number;
+    sent_count: number;
+    failed_count: number;
+    status: string;
+    error_message?: string;
+}
 /**
  * 푸시 알림 API
  *
@@ -3473,8 +4729,8 @@ interface WebPushSubscription {
  *     device_name: 'Galaxy S24',
  * })
  *
- * // 토픽 구독
- * await cb.push.subscribeTopic('announcements')
+ * // 토픽 구독 (device_token 필수)
+ * await cb.push.subscribeTopic(device.device_token, 'announcements')
  *
  * // Web Push 등록 (브라우저)
  * const vapidKey = await cb.push.getVAPIDPublicKey()
@@ -3522,52 +4778,38 @@ declare class PushAPI {
     /**
      * 디바이스 등록 해제
      *
-     * @param deviceId 디바이스 ID
+     * @param deviceToken 디바이스 토큰
      *
      * @example
      * ```typescript
-     * await cb.push.unregisterDevice('device-id-here')
+     * await cb.push.unregisterDevice('fcm-token-here')
      * ```
      */
-    unregisterDevice(deviceId: string): Promise<void>;
-    /**
-     * 현재 등록된 디바이스 목록 조회
-     *
-     * @returns 디바이스 목록
-     */
-    getDevices(): Promise<DeviceInfo[]>;
+    unregisterDevice(deviceToken: string): Promise<void>;
     /**
      * 토픽 구독
      *
+     * @param deviceToken 디바이스 토큰
      * @param topicName 토픽 이름
      *
      * @example
      * ```typescript
-     * // 공지사항 토픽 구독
-     * await cb.push.subscribeTopic('announcements')
-     *
-     * // 마케팅 토픽 구독
-     * await cb.push.subscribeTopic('marketing')
+     * await cb.push.subscribeTopic('fcm-token-here', 'announcements')
      * ```
      */
-    subscribeTopic(topicName: string): Promise<void>;
+    subscribeTopic(deviceToken: string, topicName: string): Promise<void>;
     /**
      * 토픽 구독 해제
      *
+     * @param deviceToken 디바이스 토큰
      * @param topicName 토픽 이름
      *
      * @example
      * ```typescript
-     * await cb.push.unsubscribeTopic('marketing')
+     * await cb.push.unsubscribeTopic('fcm-token-here', 'marketing')
      * ```
      */
-    unsubscribeTopic(topicName: string): Promise<void>;
-    /**
-     * 구독 중인 토픽 목록 조회
-     *
-     * @returns 구독 중인 토픽 이름 목록
-     */
-    getSubscribedTopics(): Promise<string[]>;
+    unsubscribeTopic(deviceToken: string, topicName: string): Promise<void>;
     /**
      * VAPID Public Key 조회 (Web Push용)
      *
@@ -3609,8 +4851,33 @@ declare class PushAPI {
     registerWebPush(subscription: PushSubscription | WebPushSubscription): Promise<DeviceInfo>;
     /**
      * Web Push 구독 해제
+     *
+     * @param deviceToken Web Push endpoint URL (등록 시 사용한 endpoint)
+     */
+    unregisterWebPush(deviceToken: string): Promise<void>;
+    /**
+     * 회원 ID 목록으로 푸시 발송 — Functions / cb_sk_ 인증 환경 전용.
+     *
+     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT 또는 User Secret Key
+     * (`cb_sk_`) 만 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`) 인스턴스에서는 호출
+     * 자체가 차단되며, 권한 누설을 막기 위해 명확한 에러를 던진다.
+     *
+     * @param appId 발송 대상 앱 ID (cb_sk_ 환경은 user 단위 권한이므로 명시 전달).
+     * @param memberIds 받는 회원 ID 배열 (UUID).
+     * @param payload 푸시 내용/옵션.
+     *
+     * @example
+     * ```ts
+     * // ConnectBase Function (Node.js, secrets.CB_SECRET_KEY 주입)
+     * const result = await cb.push.sendToMembers(APP_ID, [memberId], {
+     *     title: '새 알림',
+     *     body: '확인해보세요',
+     *     data: { route: '/notifications' },
+     * })
+     * console.log(result.message_id, result.sent_count)
+     * ```
      */
-    unregisterWebPush(): Promise<void>;
+    sendToMembers(appId: string, memberIds: string[], payload: SendToMembersPayload): Promise<SendPushResult>;
     /**
      * 브라우저 고유 ID 생성 (localStorage에 저장)
      */
@@ -3847,6 +5114,62 @@ interface ChannelMembership {
     started_at: string;
     expires_at?: string;
 }
+interface VideoStorage {
+    id: string;
+    app_id: string;
+    name: string;
+    description: string;
+    current_size: number;
+    video_count: number;
+    is_public: boolean;
+    allow_server_to_server: boolean;
+    allowed_origins: string[];
+    strict_referer_check: boolean;
+    cdn_provider: string;
+    cdn_config: Record<string, unknown>;
+    default_qualities: string[];
+    hls_encryption_enabled: boolean;
+    token_expiry_hours: number;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateVideoStorageRequest {
+    name: string;
+    description?: string;
+    is_public?: boolean;
+    allow_server_to_server?: boolean;
+    allowed_origins?: string[];
+    strict_referer_check?: boolean;
+    cdn_provider?: string;
+    cdn_config?: Record<string, unknown>;
+    default_qualities?: string[];
+    hls_encryption_enabled?: boolean;
+    token_expiry_hours?: number;
+}
+interface UpdateVideoStorageRequest {
+    name?: string;
+    description?: string;
+    is_public?: boolean;
+    allow_server_to_server?: boolean;
+    allowed_origins?: string[];
+    strict_referer_check?: boolean;
+    cdn_provider?: string;
+    cdn_config?: Record<string, unknown>;
+    default_qualities?: string[];
+    hls_encryption_enabled?: boolean;
+    token_expiry_hours?: number;
+}
+interface VideoStorageListResponse {
+    storage_videos: VideoStorage[];
+    total_count: number;
+}
+interface StorageUploadOptions {
+    title: string;
+    description?: string;
+    visibility?: VideoVisibility;
+    tags?: string[];
+    onProgress?: (progress: UploadProgress) => void;
+}
 interface SuperChat {
     id: string;
     video_id: string;
@@ -3888,7 +5211,29 @@ declare class VideoAPI {
      */
     waitForReady(videoId: string, options?: WaitOptions): Promise<Video>;
     /**
-     * List videos
+     * 영상 목록 조회.
+     *
+     * 필터링/페이지네이션 옵션을 조합해 조건에 맞는 영상들을 반환한다.
+     * API Key(publicKey) 또는 JWT 인증이 모두 지원되며, publicKey 로는 공개 영상만 노출된다.
+     *
+     * @param options - 필터/페이지네이션 옵션
+     * @param options.status - `uploading` | `processing` | `ready` | `failed`
+     * @param options.visibility - `public` | `unlisted` | `private` | `members`
+     * @param options.search - 제목 부분 일치 검색
+     * @param options.channel_id - 특정 채널로 한정
+     * @param options.page - 1 부터 시작
+     * @param options.limit - 기본 20, 최대 100
+     * @returns `videos` 배열과 `total` 카운트를 포함하는 응답
+     *
+     * @example
+     * ```ts
+     * // 내 채널의 최근 공개 영상 10개
+     * const { videos, total } = await cb.video.list({
+     *   channel_id: 'ch_abc',
+     *   visibility: 'public',
+     *   limit: 10,
+     * })
+     * ```
      */
     list(options?: VideoListOptions): Promise<VideoListResponse>;
     /**
@@ -3904,7 +5249,20 @@ declare class VideoAPI {
      */
     delete(videoId: string): Promise<void>;
     /**
-     * Get streaming URL for a video
+     * 영상 스트리밍 URL 획득 (HLS manifest 권장).
+     *
+     * 반환된 URL 은 `hls.js` 또는 Safari 네이티브 HLS 플레이어에 그대로 전달 가능하다.
+     * 서명된 URL 이므로 만료 시간이 존재하며, 갱신이 필요한 경우 다시 호출한다.
+     *
+     * @param videoId - 대상 영상 ID
+     * @param quality - `auto` (기본) | `1080p` | `720p` | `480p` | `360p` 등 트랜스코딩된 품질 레벨
+     * @returns HLS manifest URL 과 만료 정보
+     *
+     * @example
+     * ```ts
+     * const { url, expires_at } = await cb.video.getStreamUrl(videoId, '720p')
+     * videoElement.src = url
+     * ```
      */
     getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
     /**
@@ -4060,11 +5418,131 @@ declare class VideoAPI {
      * Submit recommendation feedback
      */
     submitFeedback(videoId: string, feedback: 'interested' | 'not_interested'): Promise<void>;
+    /**
+     * Storage sub-namespace for video storage container operations
+     */
+    readonly storage: {
+        /**
+         * Create a video storage container
+         */
+        create: (data: CreateVideoStorageRequest) => Promise<VideoStorage>;
+        /**
+         * List video storage containers
+         */
+        list: () => Promise<VideoStorageListResponse>;
+        /**
+         * Get a video storage container
+         */
+        get: (storageId: string) => Promise<VideoStorage>;
+        /**
+         * Update a video storage container
+         */
+        update: (storageId: string, data: UpdateVideoStorageRequest) => Promise<VideoStorage>;
+        /**
+         * Delete a video storage container
+         */
+        delete: (storageId: string) => Promise<void>;
+        /**
+         * Upload a video to a specific storage via core-server proxy (chunked)
+         */
+        upload: (storageId: string, file: File, options: StorageUploadOptions) => Promise<Video>;
+        /**
+         * List videos in a specific storage
+         */
+        listVideos: (storageId: string, options?: VideoListOptions) => Promise<VideoListResponse>;
+        /**
+         * Get a video in a specific storage
+         */
+        getVideo: (storageId: string, videoId: string) => Promise<Video>;
+        /**
+         * Delete a video from a specific storage
+         */
+        deleteVideo: (storageId: string, videoId: string) => Promise<void>;
+        /**
+         * Get streaming URL for a video in a specific storage
+         */
+        getStreamUrl: (storageId: string, videoId: string) => Promise<StreamURLResponse>;
+        /**
+         * Get transcode status for a video in a specific storage
+         */
+        getTranscodeStatus: (storageId: string, videoId: string) => Promise<TranscodeStatus>;
+    };
+}
+
+/**
+ * 게임 서버 기능 opt-in 토글 API.
+ *
+ * v3.1 (2026-04-30+) 부터 도입. 7개 게임 기능 (matchqueue / leaderboard / entity /
+ * scripts / voice / replay / spectator) 은 모두 앱 단위로 명시적 opt-in 해야 사용 가능.
+ *
+ * 정책:
+ *   - 신규 앱: 모든 토글 false (App 생성 시 row 자동 삽입)
+ *   - 기존 앱: row 가 없으면 레거시 호환으로 모두 ON 으로 응답 (서비스 단절 방지)
+ *   - PATCH 후 game-server 캐시는 NATS publish 로 즉시 무효화 (또는 30s TTL)
+ *
+ * @example
+ * ```ts
+ * const cfg = await cb.game.config.get(appId)
+ * if (!cfg.matchqueue_enabled) {
+ *   await cb.game.config.set(appId, { matchqueue_enabled: true })
+ * }
+ * ```
+ *
+ * @see docs/game-server/OPT_IN.md
+ */
+
+/** 7개 토글 + 메타. */
+interface GameConfig {
+    matchqueue_enabled: boolean;
+    leaderboard_enabled: boolean;
+    entity_enabled: boolean;
+    scripts_enabled: boolean;
+    voice_enabled: boolean;
+    replay_enabled: boolean;
+    spectator_enabled: boolean;
+}
+/** PATCH body — 변경할 필드만 명시 (partial update). */
+type GameConfigPatch = Partial<GameConfig>;
+/**
+ * 게임 기능 토글 클라이언트.
+ *
+ * 직접 인스턴스화하지 않고 `cb.game.config` 로 접근.
+ */
+declare class GameConfigAPI {
+    private http;
+    private appId?;
+    constructor(http: HttpClient, appId?: string);
+    /**
+     * 현재 토글 상태 조회.
+     *
+     * @param appId 앱 ID (생성자에서 주입한 기본값 사용 가능)
+     */
+    get(appId?: string): Promise<GameConfig>;
+    /**
+     * 토글 변경. 보낸 필드만 갱신, 나머지는 보존. PATCH 직후 game-server 캐시 즉시 drop
+     * (NATS publish) — TTL 기다릴 필요 없음.
+     *
+     * @example
+     * await cb.game.config.set(appId, { matchqueue_enabled: true, leaderboard_enabled: true })
+     */
+    set(appId: string | GameConfigPatch, patch?: GameConfigPatch): Promise<GameConfig>;
+    /**
+     * 단일 기능 활성화 — set() 의 편의 wrapper.
+     *
+     * @example await cb.game.config.enable(appId, "matchqueue")
+     */
+    enable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
+    /**
+     * 단일 기능 비활성화.
+     */
+    disable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
+    private resolveAppId;
 }
 
 /**
  * Game Server Types
  */
+
 /**
  * 게임 룸 설정
  */
@@ -4077,6 +5555,16 @@ interface GameRoomConfig {
     tickRate?: number;
     /** 최대 플레이어 수 (기본 100) */
     maxPlayers?: number;
+    /**
+     * 룸에 attach 할 Lua 스크립트 이름. 콘솔 또는 `POST /v1/game/:appID/scripts` 로 업로드+활성화한
+     * 스크립트만 사용 가능. 미지정 시 server tick + delta 만 흐르고 onTick / onJoin / onAction 등
+     * 사용자 hook 은 호출되지 않는다.
+     *
+     * platform-issue 019e123a (2026-05-10) 해결로 추가된 필드. 이전 버전에서 createRoom config 에
+     * `script_name` 을 직접 넣어 호출하던 워크어라운드는 SDK 가 와이어 페이로드에서 자동으로
+     * `script_name` 으로 매핑해 호환된다.
+     */
+    scriptName?: string;
     /** 커스텀 메타데이터 */
     metadata?: Record<string, string>;
 }
@@ -4144,7 +5632,7 @@ interface GameRoomInfo {
 /**
  * 게임 서버 메시지 타입
  */
-type GameServerMessageType = 'room_created' | 'room_joined' | 'room_left' | 'state' | 'delta' | 'player_event' | 'chat' | 'pong' | 'room_list' | 'error';
+type GameServerMessageType = 'room_created' | 'room_joined' | 'room_left' | 'state' | 'delta' | 'player_event' | 'chat' | 'pong' | 'room_list' | 'error' | 'room_stale' | 'sync_lost';
 /**
  * 게임 서버 메시지
  * 서버는 모든 필드를 최상위에 보냄 (data 래퍼 없음)
@@ -4181,6 +5669,30 @@ interface GameServerMessage {
     timestamp?: number;
     client_timestamp?: number;
     server_timestamp?: number;
+    phase?: string;
+    feature?: string;
+    script_id?: string;
+    /**
+     * broadcastScriptError 가 onAction 에러 broadcast 시 origin client 식별을 위해
+     * 함께 보내는 필드. sender 본인은 점대점 error 응답으로 받으므로 broadcast 에서
+     * 제외되며, 다른 player 가 누가 액션을 일으켰는지 가시화하는 용도.
+     */
+    origin_client_id?: string;
+    /**
+     * `code === 'SCRIPT_NOT_FOUND'` 응답에 포함 — createRoom 시 client 가 요청했던
+     * scriptName. 오타/대소문자/스킴 mismatch 디버깅 단서.
+     */
+    requested?: string;
+    /**
+     * `code === 'SCRIPT_NOT_FOUND'` 응답에 포함 — 현재 app 에 활성(active+version>0)
+     * 상태인 script 이름 목록. 사용자가 후보 중 골라 재시도하기 좋도록 노출.
+     */
+    available?: string[];
+    reason?: string;
+    script_version?: number;
+    /** room_created 응답 — 서버가 attach 한 lua script 이름 (검증된 값). */
+    script_name?: string;
+    hint?: string;
 }
 /**
  * 플레이어 이벤트
@@ -4202,11 +5714,74 @@ interface ChatMessage {
     serverTime: number;
 }
 /**
- * 에러 메시지
+ * GameErrorCode — game-server 가 surface 하는 에러 코드 literal union.
+ *
+ * - `SCRIPT_NOT_FOUND`     : createRoom 의 scriptName 이 미존재/비활성. 응답에 requested + available 동봉.
+ * - `NO_ACTION_HANDLER`    : action 의 type 에 대응하는 lua handler 미정의 (`onAction` 또는 `handlers[type]`).
+ * - `FEATURE_DISABLED`     : entity/matchqueue/leaderboard 등 opt-in feature 가 OFF. feature 필드로 분기.
+ * - `SCRIPT_ERROR`         : lua 실행 중 일반 에러 (분류되지 않은 throw / runtime error).
+ * - `SCRIPT_TIMEOUT`       : 사용자 hook code 의 context deadline 초과 (기본 100ms). hook 본문이 느림.
+ * - `SCRIPT_SETUP_OVERRUN` : hook 호출 *전* 플랫폼 측 setup phase (스크립트 로드 + state 직렬화 + API 주입) 가
+ *                            setupBudget(기본 100ms / onInit 1s) 초과. 일반적으로 룸 state 가 너무 큼.
+ *                            해결: state 의 큰 데이터를 entity primitive 로 이전, state.dbg.* 누적 중단.
+ *                            issue 019e2c29 후 도입 (2026-05-16).
+ * - `RATE_LIMITED`         : per-app script rate limit 초과 (`SCRIPT_RATE_PER_SEC`).
+ * - `QUOTA_EXCEEDED`       : plan 한도(`script_executions/month`) 초과.
+ * - `TIMEOUT`              : SDK 측 sendWithHandler timeout (서버 응답 없음).
+ * - `UNKNOWN`              : 분류되지 않은 server 에러 (server 에 신규 코드가 생겼는데 SDK 미반영).
+ *
+ * literal autocomplete 를 유지하면서 미래에 server 가 신규 코드를 추가해도 타입 에러가
+ * 안 나도록 `string & {}` 도 union 에 포함 (TypeScript 'string literal type widening' 우회 패턴).
+ */
+type GameErrorCode = 'SCRIPT_NOT_FOUND' | 'NO_ACTION_HANDLER' | 'FEATURE_DISABLED' | 'SCRIPT_ERROR' | 'SCRIPT_TIMEOUT' | 'SCRIPT_SETUP_OVERRUN' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'TIMEOUT' | 'UNKNOWN' | (string & {});
+/**
+ * 에러 메시지 — server `error` 메시지의 wire format. SDK 사용자에게는 GameError
+ * 인스턴스(class)로 surface 되지만, 본 인터페이스는 raw payload 매핑 + 타입 추론용.
  */
 interface ErrorMessage {
-    code: string;
+    code: GameErrorCode;
     message: string;
+    /**
+     * 서버측 Lua hook 단계 식별자 — 값이 있으면 lua 실행 에러.
+     * "onJoin" | "onLeave" | "onTick" | "onAction".
+     * 일반 transport / protocol 에러는 phase 없음.
+     */
+    phase?: 'onJoin' | 'onLeave' | 'onTick' | 'onAction' | (string & {});
+    /**
+     * code === "FEATURE_DISABLED" 일 때 비활성 feature 이름.
+     * "entity" | "matchqueue" | "leaderboard" 등 — `toggle_game_features` 와 1:1 매핑.
+     */
+    feature?: 'entity' | 'matchqueue' | 'leaderboard' | (string & {});
+    roomId?: string;
+    scriptId?: string;
+    /**
+     * broadcast 형태의 onAction 에러일 때 액션을 일으킨 client. 본인이 아닌 다른
+     * player 에서 발생한 에러를 SDK 사용자가 식별/필터링하기 위한 필드.
+     */
+    originClientId?: string;
+    /** code === 'SCRIPT_NOT_FOUND' 시 client 가 요청했던 scriptName. */
+    requested?: string;
+    /** code === 'SCRIPT_NOT_FOUND' 시 후보로 노출되는 active script 이름 목록. */
+    available?: string[];
+}
+/**
+ * CreateRoomResult — `createRoomDetailed` 의 반환 타입. createRoom 의 호환성 보존을
+ * 위해 별도 메서드로 노출 (createRoom 은 기존대로 `Promise<GameState>` 유지).
+ *
+ * server 의 `room_created` 응답에는 이전엔 room_id + initial_state 만 들어왔으나
+ * platform-issue 019e21dd (NJB regression, 2026-05-13) 의 회귀 가드로 attach 된 lua
+ * script 의 이름/버전이 함께 echo 된다 — client 가 attach 검증 후 mismatch 시
+ * 즉시 throw 할 수 있도록.
+ */
+interface CreateRoomResult {
+    /** 서버 생성 룸 UUID (config.roomId 와 항상 같지는 않음 — 서버가 fresh UUID 생성 가능). */
+    roomId: string;
+    /** 초기 상태 스냅샷. 기존 `createRoom` 의 resolve 값과 동일 shape. */
+    state: GameState;
+    /** Attached lua script 이름. config.scriptName 미지정 시 undefined. */
+    scriptName?: string;
+    /** Attached lua script 의 active version (Manager.GetMeta.ActiveVersion). */
+    scriptVersion?: number;
 }
 /**
  * Ping/Pong 응답
@@ -4215,13 +5790,38 @@ interface PongMessage {
     clientTimestamp: number;
     serverTimestamp: number;
 }
+/**
+ * room_stale 이벤트 페이로드.
+ * 서버 측 hot reload(active_version bump) 등으로 현재 room 의 lua 핸들러가
+ * 갱신됐지만 기존 state 가 보존되어 사용자 lua 의 `state.initialized` 같은
+ * 가드로 `handlers.init` 가 재실행되지 않을 수 있을 때 발화된다.
+ *
+ * 권장 처리: leaveRoom → joinRoom 또는 새 roomId 로 createRoom.
+ * 자동 disconnect 는 SDK 가 하지 않는다 — 정책은 사용자 게임이 결정.
+ */
+interface RoomStaleMessage {
+    /** "script_reloaded" | "schema_changed" | "manual" 등 — 자유 문자열 */
+    reason: string;
+    roomId: string;
+    /** appID:scriptName 형태. 없을 수 있음. */
+    scriptId?: string;
+    /** 새 active_version. 없을 수 있음. */
+    scriptVersion?: number;
+    serverTime: number;
+}
 /**
  * 게임 클라이언트 이벤트 핸들러
  */
 interface GameEventHandlers {
     onConnect?: () => void;
     onDisconnect?: (event: CloseEvent) => void;
-    onError?: (error: Event | ErrorMessage) => void;
+    /**
+     * - `Event` : WebSocket transport-level 에러 (브라우저 WS API 의 onerror).
+     * - `GameError` : server 가 surface 한 `error` 메시지를 wrap 한 인스턴스 — `.code`,
+     *   `.phase`, `.feature`, `.originClientId`, `.requested`, `.available` 모두 노출.
+     *   `instanceof GameError` 로 분기하여 UI 표시 차별화 가능.
+     */
+    onError?: (error: Event | GameError) => void;
     onStateUpdate?: (state: GameState) => void;
     onDelta?: (delta: GameDelta) => void;
     onAction?: (action: {
@@ -4234,6 +5834,22 @@ interface GameEventHandlers {
     onPlayerLeft?: (player: GamePlayer) => void;
     onChat?: (message: ChatMessage) => void;
     onPong?: (pong: PongMessage) => void;
+    /**
+     * 커스텀 broadcast 메시지 핸들러 — 서버 Lua 의 `room.broadcast(data)` / `room.send_to(clientId, data)`
+     * 로 보낸, SDK 가 모르는 `type` 의 메시지가 여기로 흘러온다. `delta`/`state`/`chat`/`player_event`/`error`
+     * 같은 표준 타입은 전용 핸들러로 가고 여기엔 오지 않는다.
+     *
+     * 게임별 커스텀 프로토콜(예: `{ type: "chunk", ... }`, `{ type: "turn_played", ... }`)은
+     * 이 핸들러에서 `msg.type` 으로 분기한다.
+     */
+    onMessage?: (msg: Record<string, unknown> & {
+        type: string;
+    }) => void;
+    /**
+     * 서버가 room 을 stale 로 표시했을 때 발화. 자세한 사양은 `RoomStaleMessage` 참고.
+     * 미설정 시 SDK 는 console.warn 으로 가시화만 하고 자동 동작은 하지 않는다.
+     */
+    onRoomStale?: (msg: RoomStaleMessage) => void;
 }
 /**
  * 게임 클라이언트 설정
@@ -4243,8 +5859,8 @@ interface GameClientConfig {
     gameServerUrl?: string;
     /** 앱 ID */
     appId?: string;
-    /** API Key */
-    apiKey?: string;
+    /** Public Key */
+    publicKey?: string;
     /** 액세스 토큰 */
     accessToken?: string;
     /** 클라이언트 ID */
@@ -4374,7 +5990,202 @@ interface LobbyInvite {
     createdAt: string;
     expiresAt: string;
 }
+interface PartyInfo {
+    id: string;
+    app_id: string;
+    leader_id: string;
+    members: PartyMember[];
+    max_size: number;
+    settings?: Record<string, string>;
+    state: string;
+    created_at: string;
+    updated_at: string;
+}
+interface PartyMember {
+    player_id: string;
+    display_name?: string;
+    ready: boolean;
+    role: string;
+    joined_at: string;
+    metadata?: Record<string, string>;
+}
+interface PartyInvite {
+    invite_id: string;
+    party_id: string;
+    inviter_id: string;
+    status: string;
+    expires_at: string;
+}
+interface SpectatorInfo {
+    id: string;
+    user_id?: string;
+    room_id: string;
+    mode: "free" | "follow" | "director";
+    target_id?: string;
+    joined_at: string;
+    delay_seconds?: number;
+}
+interface SpectatorState {
+    room_id: string;
+    tick: number;
+    timestamp: number;
+    players: SpectatorPlayerState[];
+    game_state?: Record<string, unknown>;
+    events?: Record<string, unknown>[];
+}
+interface SpectatorPlayerState {
+    id: string;
+    display_name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    health?: number;
+    score?: number;
+    is_alive: boolean;
+}
+interface LeaderboardEntry {
+    rank: number;
+    player_id: string;
+    display_name: string;
+    rating: number;
+    wins: number;
+    losses: number;
+    games_played: number;
+    win_rate: number;
+    tier: string;
+    division: number;
+    updated_at: string;
+}
+interface PlayerStats {
+    player_id: string;
+    rating: number;
+    wins: number;
+    losses: number;
+    games_played: number;
+    win_rate: number;
+    tier: string;
+    division: number;
+    match_history: MatchResult[];
+}
+interface MatchResult {
+    match_id: string;
+    result: "win" | "loss" | "draw";
+    rating_change: number;
+    played_at: string;
+}
+interface VoiceChannel {
+    id: string;
+    room_id: string;
+    name: string;
+    type: "global" | "team" | "proximity" | "private" | "spectator";
+    team_id?: string;
+    max_members: number;
+    members: Record<string, VoiceMember>;
+    webrtc_room_id: string;
+    created_at: string;
+}
+interface VoiceMember {
+    player_id: string;
+    display_name: string;
+    joined_at: string;
+    webrtc_url?: string;
+}
+interface ReplayInfo {
+    id: string;
+    room_id: string;
+    game_type: string;
+    map_name?: string;
+    duration: number;
+    tick_rate: number;
+    start_tick: number;
+    end_tick: number;
+    players: ReplayPlayerInfo[];
+    file_size: number;
+    created_at: string;
+    schema_version?: string;
+}
+interface ReplayPlayerInfo {
+    player_id: string;
+    display_name: string;
+    team_id?: string;
+}
+interface ReplayHighlight {
+    tick: number;
+    type: string;
+    actor_id: string;
+    score: number;
+}
+/** Matchqueue ticket — attributes 는 free-form (rating/region 등 자유). */
+interface MatchqueueTicket {
+    ticket_id: string;
+    queue_key: string;
+    attributes?: Record<string, unknown>;
+    enqueued_at: string;
+    ttl_at?: string;
+}
+interface MatchqueueListResponse {
+    tickets: MatchqueueTicket[];
+    count: number;
+}
+/**
+ * v3.0 Leaderboard score entry — score 는 사용자 Lua 의 ELO/MMR 공식 결과.
+ * rank 는 GetTop/GetRank 시점에만 채워진다 (저장은 안 됨).
+ *
+ * v2.x 의 LeaderboardEntry (player_id/rating/tier/wins/losses 등) 와 다른 시그니처라
+ * 새 이름 사용. v2 LeaderboardEntry 는 v3.0 에서 deprecated.
+ */
+interface LeaderboardScoreEntry {
+    member: string;
+    score: number;
+    updated_at: string;
+    rank?: number;
+}
+interface LeaderboardListResponse {
+    entries: LeaderboardScoreEntry[];
+    count: number;
+}
+/** Lua script — 메타 + 단일 버전. */
+interface ScriptMeta {
+    app_id: string;
+    name: string;
+    active_version: number;
+    latest_version: number;
+    status: "active" | "staging" | "disabled";
+    updated_at: string;
+}
+interface ScriptVersion {
+    app_id: string;
+    name: string;
+    version: number;
+    hash: string;
+    code: string;
+    uploaded_at: string;
+    uploaded_by?: string;
+}
+interface ScriptListResponse {
+    scripts: ScriptMeta[];
+    count: number;
+}
+interface ScriptVersionListResponse {
+    versions: ScriptVersion[];
+    count: number;
+}
+interface ScriptDetailResponse {
+    meta: ScriptMeta;
+    active?: ScriptVersion;
+}
 
+/**
+ * 게임 서버 `create_room` 메시지 페이로드는 snake_case 필드를 기대한다 (Go 핸들러 JSON 태그).
+ * SDK 의 GameRoomConfig 는 camelCase 이므로, scriptName / tickRate / maxPlayers / roomId /
+ * categoryId 를 와이어 형식으로 매핑한다. 추가 필드(metadata)는 그대로 통과.
+ *
+ * platform-issue 019e123a (2026-05-10) 의 회귀 가드 — scriptName 누락 시 RoomConfig.ScriptID
+ * 가 비어 onTick / onPlayerJoin 등이 silent skip 되던 문제 차단.
+ */
+declare function toCreateRoomWire(config: GameRoomConfig): Record<string, unknown>;
 /**
  * 게임 룸 클라이언트
  * WebSocket 연결을 관리하고 게임 상태를 동기화합니다.
@@ -4389,6 +6200,8 @@ declare class GameRoom {
     private actionSequence;
     private _roomId;
     private _state;
+    private _scriptName;
+    private _scriptVersion;
     private _isConnected;
     constructor(config: GameClientConfig);
     /**
@@ -4416,9 +6229,29 @@ declare class GameRoom {
      */
     disconnect(): void;
     /**
-     * 룸 생성
+     * 룸 생성 (호환 시그니처) — 초기 상태만 반환.
+     *
+     * Attached script 의 검증(scriptName/scriptVersion echo 검사) 이 필요하면
+     * 인스턴스 getter (`room.scriptName`, `room.scriptVersion`) 를 함께 사용하거나,
+     * 메타까지 한 번에 받고 싶다면 {@link createRoomDetailed} 를 사용한다.
+     *
+     * 미존재/비활성 scriptName 은 서버가 `SCRIPT_NOT_FOUND` 로 즉시 reject 한다.
+     * reject 값은 `GameError` 인스턴스이며 `.code`/`.requested`/`.available` 로 분기 가능.
      */
     createRoom(config?: GameRoomConfig): Promise<GameState>;
+    /**
+     * 룸 생성 + 메타 — server 가 attach 한 lua script 이름/버전을 함께 반환.
+     *
+     * @example
+     * const { state, scriptName, scriptVersion } = await room.createRoomDetailed({ scriptName: 'njb-main' })
+     * if (scriptName !== 'njb-main') throw new Error('script mismatch')
+     * console.log('attached', scriptName, 'v', scriptVersion)
+     */
+    createRoomDetailed(config?: GameRoomConfig): Promise<CreateRoomResult>;
+    /** Attached lua script 이름 — createRoom 이후 server 가 echo 한 값. */
+    get scriptName(): string | null;
+    /** Attached lua script 의 active version. */
+    get scriptVersion(): number | null;
     /**
      * 룸 참가
      */
@@ -4467,9 +6300,18 @@ declare class GameAPI {
     private http;
     private gameServerUrl;
     private appId?;
+    /**
+     * 게임 기능 opt-in 토글 (v3.1+). `cb.game.config.get/set` 으로 호출.
+     * 자세한 내용은 [GameConfigAPI] 참고.
+     */
+    readonly config: GameConfigAPI;
     constructor(http: HttpClient, gameServerUrl?: string, appId?: string);
     /**
-     * 게임 룸 클라이언트 생성
+     * 게임 룸 클라이언트 생성.
+     *
+     * `appId` 는 `createClient({ appId })` 로 호출별 지정하거나, 생략 시 `new ConnectBase({ appId })`
+     * 의 전역 값을 사용한다. 둘 다 없으면 `connect()` 가 명확한 에러로 reject 한다 — 빈 appId 로
+     * `/v1/game//ws` 에 붙어 server 측이 SCRIPT_NOT_FOUND 로 깨지던 silent 회귀 차단 (NJB 019e2210).
      */
     createClient(config: Omit<GameClientConfig, 'gameServerUrl'>): GameRoom;
     /**
@@ -4482,98 +6324,138 @@ declare class GameAPI {
     getRoom(roomId: string): Promise<GameRoomInfo>;
     /**
      * 룸 생성 (HTTP, gRPC 대안)
+     *
+     * @deprecated 현재 SDK public 경로로 노출되지 않습니다. 콘솔(admin) 에서 진행하거나 백엔드 public 경로 오픈을 요청하세요.
      */
-    createRoom(appId: string, config?: GameRoomConfig): Promise<GameRoomInfo>;
+    createRoom(_appId: string, _config?: GameRoomConfig): Promise<GameRoomInfo>;
     /**
      * 룸 삭제 (HTTP)
-     */
-    deleteRoom(roomId: string): Promise<void>;
+     *
+     * @deprecated 현재 SDK public 경로로 노출되지 않습니다. 콘솔(admin) 에서 진행하거나 백엔드 public 경로 오픈을 요청하세요.
+     */
+    deleteRoom(_roomId: string): Promise<void>;
+    joinSpectator(roomId: string, playerId: string): Promise<SpectatorInfo>;
+    leaveSpectator(roomId: string, spectatorId: string): Promise<void>;
+    getSpectators(roomId: string): Promise<SpectatorInfo[]>;
+    joinVoiceChannel(roomId: string, playerId: string): Promise<VoiceChannel>;
+    leaveVoiceChannel(roomId: string, playerId: string): Promise<void>;
+    setMute(playerId: string, muted: boolean): Promise<void>;
+    listReplays(roomId?: string): Promise<ReplayInfo[]>;
+    getReplay(replayId: string): Promise<ReplayInfo>;
+    downloadReplay(replayId: string): Promise<ArrayBuffer>;
+    getReplayHighlights(replayId: string): Promise<ReplayHighlight[]>;
+    private getHeaders;
+    private gameFetch;
     /**
-     * 매치메이킹 큐에 참가
+     * matchqueue 에 ticket 등록.
+     *
+     * @example
+     * await cb.game.enqueueMatch(appId, "ranked", userId, {
+     *   rating: 1500, region: "asia", team_size: 5,
+     * }, 60)
+     *
+     * @constraints appId/queueKey/ticketId 는 [a-zA-Z0-9_-] 만 허용. ttlSec=0 이면 만료 없음.
      */
-    joinQueue(req: JoinQueueRequest): Promise<MatchmakingTicket>;
+    enqueueMatch(appId: string, queueKey: string, ticketId: string, attributes?: Record<string, unknown>, ttlSec?: number): Promise<MatchqueueTicket>;
     /**
-     * 매치메이킹 큐에서 탈퇴
+     * matchqueue 의 모든 ticket 목록 반환. 사용자 Lua 가 매칭 후보 선별에 사용.
+     *
+     * @example const tickets = await cb.game.listMatchqueue(appId, "ranked")
      */
-    leaveQueue(ticketId: string): Promise<void>;
+    listMatchqueue(appId: string, queueKey: string): Promise<MatchqueueListResponse>;
     /**
-     * 매치메이킹 상태 조회
+     * 매칭 큐에서 ticket 제거 (예: 사용자가 매칭 취소).
      */
-    getMatchStatus(params: {
-        ticketId?: string;
-        playerId?: string;
-    }): Promise<MatchmakingTicket>;
+    cancelMatch(appId: string, queueKey: string, ticketId: string): Promise<void>;
     /**
-     * 로비 목록 조회
+     * leaderboard 점수 기록. mode="set" (기본, overwrite) 또는 "incr" (증감).
+     *
+     * @example
+     * await cb.game.submitScore(appId, "global_elo", userId, 32, "incr")
      */
-    listLobbies(): Promise<LobbyInfo[]>;
+    submitScore(appId: string, leaderboardKey: string, member: string, score: number, mode?: "set" | "incr"): Promise<LeaderboardScoreEntry>;
     /**
-     * 로비 생성
+     * 상위 n 명 조회 (기본 10).
      */
-    createLobby(req: CreateLobbyRequest): Promise<LobbyInfo>;
+    getTopScores(appId: string, leaderboardKey: string, n?: number): Promise<LeaderboardListResponse>;
     /**
-     * 로비 상세 조회
+     * 단일 member 의 rank + score.
      */
-    getLobby(lobbyId: string): Promise<LobbyInfo>;
+    getMemberRank(appId: string, leaderboardKey: string, member: string): Promise<LeaderboardScoreEntry>;
     /**
-     * 로비 참가
+     * member 주변 (위 above 명 + 본인 + 아래 below 명) 조회.
      */
-    joinLobby(lobbyId: string, playerId: string, displayName?: string, password?: string): Promise<{
-        lobbyId: string;
-    }>;
+    getRankAround(appId: string, leaderboardKey: string, member: string, above?: number, below?: number): Promise<LeaderboardListResponse>;
     /**
-     * 로비 퇴장
+     * leaderboard 전체 reset (시즌 종료 시).
      */
-    leaveLobby(lobbyId: string, playerId: string): Promise<void>;
+    resetLeaderboard(appId: string, leaderboardKey: string): Promise<void>;
     /**
-     * 레디 상태 토글
+     * 특정 member 만 제거 (계정 삭제 등).
      */
-    toggleReady(lobbyId: string, playerId: string, ready: boolean): Promise<void>;
+    removeFromLeaderboard(appId: string, leaderboardKey: string, member: string): Promise<void>;
     /**
-     * 게임 시작 (호스트만)
+     * 새 스크립트 버전 업로드 (latest+1). idempotent — 동일 hash 면 새 버전 만들지 않음.
+     *
+     * @example
+     * await cb.game.uploadScript(appId, "ranked_br", fs.readFileSync("./ranked.lua", "utf-8"))
      */
-    startGame(lobbyId: string, hostId: string): Promise<{
-        roomId: string;
-    }>;
+    uploadScript(appId: string, name: string, code: string): Promise<ScriptVersion>;
     /**
-     * 플레이어 추방 (호스트만)
+     * app 의 모든 스크립트 메타데이터 목록.
      */
-    kickPlayer(lobbyId: string, hostId: string, targetPlayerId: string): Promise<void>;
+    listScripts(appId: string): Promise<ScriptListResponse>;
     /**
-     * 로비 설정 업데이트 (호스트만)
+     * 단일 스크립트 메타 + active version code.
      */
-    updateLobby(lobbyId: string, req: UpdateLobbyRequest): Promise<LobbyInfo>;
+    getScript(appId: string, name: string): Promise<ScriptDetailResponse>;
     /**
-     * 로비 채팅 전송
+     * 단일 스크립트의 모든 버전 이력.
      */
-    sendLobbyChat(lobbyId: string, playerId: string, message: string): Promise<void>;
+    listScriptVersions(appId: string, name: string): Promise<ScriptVersionListResponse>;
     /**
-     * 플레이어 초대
+     * 특정 버전 활성화 (hot reload 자동). version=0 또는 미지정 → latest 활성화.
      */
-    invitePlayer(lobbyId: string, inviterId: string, inviteeId: string): Promise<LobbyInvite>;
+    activateScript(appId: string, name: string, version?: number): Promise<ScriptMeta>;
     /**
-     * 초대 수락
+     * 직전 active 버전으로 롤백 (hot reload 자동).
      */
-    acceptInvite(inviteId: string, playerId: string, displayName?: string): Promise<{
-        lobbyId: string;
-    }>;
+    rollbackScript(appId: string, name: string): Promise<ScriptMeta>;
     /**
-     * 초대 거절
+     * 스크립트 비활성화 (status=disabled, ActiveVersion=0). 코드/모든 버전은 보존되며
+     * 이후 {@link activateScript} 로 재활성화할 수 있다.
+     *
+     * v3.14.0 BREAKING — 이전엔 `disableScript` 가 `DELETE /scripts/:name` 을 호출해
+     * Disable 매핑이었으나, server 측 `DELETE` 가 hard-delete 로 분리됨에 따라
+     * `POST /scripts/:name/deactivate` 로 endpoint 이동. 메서드명도 의도 명확화 위해 rename.
      */
-    declineInvite(inviteId: string, playerId: string): Promise<void>;
+    deactivateScript(appId: string, name: string): Promise<void>;
     /**
-     * 플레이어의 받은 초대 목록
+     * 스크립트 영구 삭제 (hard-delete) — 메타 + 모든 버전 영구 제거. 복구 불가.
+     *
+     * 잘못 업로드된 스크립트나 더 이상 사용하지 않는 슬롯을 정리할 때 사용. 단순 비활성화는
+     * {@link deactivateScript} 를 사용한다 (코드 보존, 재활성화 가능).
+     *
+     * v3.14.0 신규 — server 측 `DELETE /scripts/:name` 의 의미가 Disable → hard-delete 로
+     * 변경된 것에 대응.
      */
-    getPlayerInvites(playerId: string): Promise<LobbyInvite[]>;
-    private getHeaders;
+    deleteScript(appId: string, name: string): Promise<void>;
 }
 
-interface GoogleConnectionStatus {
+interface AdsenseConnectionInfo {
+    is_connected: boolean;
+    email?: string;
+    account_id?: string;
+}
+interface AdmobConnectionInfo {
     is_connected: boolean;
     email?: string;
-    adsense_account_id?: string;
-    admob_account_id?: string;
-    admob_publisher_id?: string;
+    account_id?: string;
+    publisher_id?: string;
+}
+interface GoogleConnectionStatus {
+    adsense: AdsenseConnectionInfo;
+    admob: AdmobConnectionInfo;
 }
 interface AdReportSummary {
     total_earnings: number;
@@ -4625,15 +6507,18 @@ declare class AdsAPI {
      */
     private getPublicPrefix;
     /**
-     * AdSense 연결 상태 확인
+     * AdSense / AdMob 연결 상태 확인 (중첩 구조)
      *
-     * @returns 연결 상태, 이메일, AdSense 계정 ID
+     * @returns `{ adsense, admob }` 각각 연결 상태·이메일·계정 ID
      *
      * @example
      * ```typescript
      * const status = await cb.ads.getConnectionStatus()
-     * if (status.is_connected) {
-     *     console.log('연결됨:', status.email)
+     * if (status.adsense.is_connected) {
+     *     console.log('AdSense 연결됨:', status.adsense.email, status.adsense.account_id)
+     * }
+     * if (status.admob.is_connected) {
+     *     console.log('AdMob 연결됨:', status.admob.account_id, status.admob.publisher_id)
      * }
      * ```
      */
@@ -4708,7 +6593,7 @@ declare class AdsAPI {
  * ```typescript
  * import ConnectBase from 'connectbase-client'
  *
- * const cb = new ConnectBase({ apiKey: 'your-api-key' })
+ * const cb = new ConnectBase({ publicKey: 'your-public-key' })
  *
  * // 플랫폼 감지
  * const platform = cb.native.getPlatform() // 'web' | 'mobile' | 'desktop'
@@ -5166,7 +7051,47 @@ interface CreateDocumentRequest {
     source_type?: 'file' | 'text' | 'url';
     content?: string;
     source_url?: string;
+    /**
+     * source_type='file' 일 때 사용. 바이너리를 base64 로 인코딩해서 보낸다.
+     * 서버가 PDF / DOCX / text 류를 자동으로 텍스트 추출 → 청킹·인덱싱 한다.
+     * 파일 50MB 상한, 이미지 OCR / 스캔 PDF 는 미지원.
+     * 일반적으로는 [`KnowledgeAPI.addDocumentFromFile`](../api/knowledge.ts) 헬퍼를 사용하면
+     * Blob / File 로 직접 넘길 수 있다.
+     */
+    file_content?: string;
+    /**
+     * file_content 의 MIME (예: 'application/pdf',
+     * 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'text/markdown').
+     * 비어있으면 서버가 매직 바이트로 자동 추정 — 정확도를 위해 명시 권장.
+     */
+    mime_type?: string;
+    /**
+     * 클라이언트가 지정하는 멱등(upsert) 키. 같은 지식 베이스 안에서 유일하다.
+     * 같은 `external_id` 로 다시 `addDocument` 하면 새 문서를 만들지 않고 기존 문서를
+     * 교체(update)한다 — `listDocuments` 로 기존 문서를 찾아 지울 필요 없이
+     * idempotent 한 동기화가 가능하다. 문서 id 도 그대로 유지된다.
+     */
+    external_id?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 문서 update/upsert 요청. 보낸 필드만 교체된다 (생략한 필드는 변경 없음).
+ *
+ * `content` / `file_content` / `metadata` 중 하나라도 보내면 서버가 전체 재색인을 수행한다
+ * (기존 청크 삭제 → 재청킹 → 재색인). RAG 특성상 콘텐츠가 바뀌면 청크 경계가 바뀌어
+ * 부분 수정이 불가능하며, 재색인 시 색인 토큰이 다시 과금된다.
+ * `name` / `external_id` 만 보내면 재색인 없이 라벨·멱등 키만 변경된다.
+ * 문서 id 는 항상 유지되므로 검색 결과의 `document_id` 참조가 깨지지 않는다.
+ */
+interface UpdateDocumentRequest {
+    name?: string;
+    content?: string;
+    /** base64 인코딩 파일 (파일 재업로드, PDF/DOCX/text). content 보다 우선하며 source_type 무관하게 추출. */
+    file_content?: string;
+    /** file_content 의 MIME. 비어있으면 서버 자동 추정. */
+    mime_type?: string;
     metadata?: Record<string, unknown>;
+    external_id?: string;
 }
 interface DocumentResponse {
     id: string;
@@ -5174,6 +7099,7 @@ interface DocumentResponse {
     source_type: string;
     mime_type?: string;
     source_url?: string;
+    external_id?: string;
     file_size: number;
     chunk_count: number;
     status: 'pending' | 'processing' | 'ready' | 'failed';
@@ -5188,9 +7114,35 @@ interface ListDocumentsResponse {
     documents: DocumentResponse[];
     total_count: number;
 }
+/**
+ * 사용자 격리용 magic 토큰. `where` 값에 이 문자열을 넣으면 서버가
+ * 인증된 AppMember ID 로 자동 치환한다 (클라이언트 변조 불가).
+ *
+ * AppMember JWT 가 함께 오지 않은 호출에서 사용하면 401.
+ */
+declare const AUTH_MEMBER_ID_TOKEN: "$auth.member_id";
+/**
+ * 검색 요청
+ * @example { query: "환불 방법", top_k: 5, agentic: true }
+ *
+ * 사용자별 격리 (AppMember JWT 가 Authorization 헤더로 함께 올 때):
+ * - 서버가 자동으로 본인 metadata.user_id 문서로 결과를 제한.
+ * - `where` 로 추가 필터를 걸 수 있음. magic 토큰 사용 예:
+ *   `where: { 'metadata.tag': 'work' }`
+ */
 interface KnowledgeSearchRequest {
+    /** 검색 쿼리 (필수) */
     query: string;
+    /** 반환할 결과 수 (기본: KB 설정값) */
     top_k?: number;
+    /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
+    agentic?: boolean;
+    /**
+     * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
+     * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
+     * AppMember JWT 컨텍스트가 있으면 서버가 추가로 metadata.user_id 강제 필터를 AND.
+     */
+    where?: Record<string, unknown>;
 }
 interface KnowledgeSearchResult {
     chunk_id: string;
@@ -5206,29 +7158,44 @@ interface KnowledgeSearchResponse {
     query: string;
     results: KnowledgeSearchResult[];
     total: number;
-}
-interface ChatRequest {
-    message: string;
-    top_k?: number;
-    model?: string;
-    stream?: boolean;
-}
-interface ChatResponse {
-    answer: string;
-    sources: KnowledgeSearchResult[];
-    model: string;
-    token_used?: number;
+    /**
+     * 이 응답이 agentic 다중검색으로 생성됐는지 여부. `agentic: true` 를 보냈더라도
+     * AI provider 미설정·LLM 오류로 단일 키워드 검색에 폴백되면 `false` — 옵션이
+     * placebo 가 되지 않도록 실제 수행 여부를 신호한다.
+     */
+    agentic?: boolean;
+    /** 수행된 agentic 검색 라운드 수 (1~2). 0 또는 미존재는 폴백을 의미. */
+    agentic_rounds?: number;
 }
 
+/**
+ * `addDocumentFromFile` 입력 형식.
+ *
+ * - `File` (DOM) — 브라우저 `<input type="file">` 결과를 그대로 사용. name / type 이 자동 추출됨.
+ * - `Blob` (DOM) — Blob.type 이 MIME 으로 사용됨 (없으면 서버 자동 추정).
+ * - `{ data, mimeType?, name? }` — Node.js Buffer / Uint8Array. mimeType 명시 권장.
+ */
+type KnowledgeFileInput = File | Blob | {
+    data: Uint8Array | ArrayBuffer;
+    mimeType?: string;
+    name?: string;
+};
 /**
  * Knowledge Base API
  *
- * RAG(Retrieval-Augmented Generation)를 위한 문서 저장 및 검색 API.
+ * AI 데이터베이스를 위한 문서 저장 및 검색 API.
  * 문서를 업로드하면 자동으로 청킹되어 키워드 기반 검색이 가능합니다.
  *
+ * ## 사용자별 격리 (다중 사용자 RAG 시나리오)
+ *
+ * `Authorization: Bearer <appmember-jwt>` 를 함께 보내면 서버가:
+ * - 검색 결과를 본인 문서 (metadata.user_id == member_id) 로 제한
+ * - addDocument 시 metadata.user_id 자동 태깅
+ * - listDocuments / deleteDocument 도 본인 자료만 노출
+ *
  * @example
  * ```typescript
- * const cb = new ConnectBase({ apiKey: 'your-api-key' })
+ * const cb = new ConnectBase({ publicKey: 'your-public-key' })
  *
  * // 텍스트 문서 추가
  * await cb.knowledge.addDocument('kb-id', {
@@ -5237,93 +7204,588 @@ interface ChatResponse {
  *     content: '환불은 구매 후 7일 이내에 가능합니다...'
  * })
  *
- * // 문서 검색
- * const results = await cb.knowledge.search('kb-id', {
- *     query: '환불 정책',
- *     top_k: 5
+ * // 문서 검색
+ * const results = await cb.knowledge.search('kb-id', {
+ *     query: '환불 정책',
+ *     top_k: 5
+ * })
+ *
+ * // 사용자별 격리 + 추가 필터 (AppMember JWT 가 같이 와야 함)
+ * const results = await cb.knowledge.search('kb-id', {
+ *     query: '내 메모',
+ *     where: { 'metadata.tag': 'work' },
+ * })
+ * ```
+ */
+declare class KnowledgeAPI {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 문서 추가
+     *
+     * 지식 베이스에 새 문서를 추가합니다. 텍스트 소스인 경우 즉시 처리됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param data - 문서 생성 요청
+     * @returns 생성된 문서 정보
+     *
+     * @example
+     * ```typescript
+     * // 텍스트 문서
+     * const doc = await cb.knowledge.addDocument('kb-id', {
+     *     name: 'FAQ',
+     *     source_type: 'text',
+     *     content: '자주 묻는 질문들...'
+     * })
+     *
+     * // URL에서 가져오기
+     * const doc2 = await cb.knowledge.addDocument('kb-id', {
+     *     name: '도움말',
+     *     source_type: 'url',
+     *     source_url: 'https://example.com/help.html'
+     * })
+     *
+     * // external_id 로 idempotent 동기화 (빌드 스크립트 등)
+     * // 같은 external_id 로 다시 호출하면 기존 문서를 교체한다 (문서 id 유지).
+     * await cb.knowledge.addDocument('kb-id', {
+     *     name: '블로그: 제목',
+     *     source_type: 'text',
+     *     content: '...',
+     *     external_id: 'blog/my-post-slug',
+     * })
+     * ```
+     */
+    addDocument(kbID: string, data: CreateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 문서 수정 (update/upsert)
+     *
+     * 기존 문서의 내용·이름·메타데이터를 교체합니다. **문서 id 는 그대로 유지**되므로
+     * 검색 결과의 `document_id` 를 외부에서 참조(인용·캐시)해도 편집 후 깨지지 않습니다.
+     * 보낸 필드만 교체되며, 내용/이름/메타데이터가 실제로 바뀌면 자동으로 재청킹·재색인됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param docID - 문서 ID
+     * @param data - 변경할 필드 (생략한 필드는 변경 없음)
+     * @returns 수정된 문서 정보
+     *
+     * @example
+     * ```typescript
+     * // 내용만 교체 — document_id 는 그대로
+     * const doc = await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     content: '갱신된 환불 정책...',
+     * })
+     *
+     * // 이름 + 메타데이터 교체
+     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
+     *     name: 'FAQ (2026)',
+     *     metadata: { tag: 'faq', updated: '2026-05' },
+     * })
+     * ```
+     */
+    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
+    /**
+     * 파일로 문서 수정 (PDF / DOCX / text 파일 재업로드).
+     *
+     * [`addDocumentFromFile`](#addDocumentFromFile) 의 update 버전. 문서 id 는 유지됩니다.
+     *
+     * @param kbID - Knowledge Base ID
+     * @param docID - 문서 ID
+     * @param file - 새 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+     * @param options - name / metadata 오버라이드
+     * @returns 수정된 문서 정보
+     */
+    updateDocumentFromFile(kbID: string, docID: string, file: KnowledgeFileInput, options?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<DocumentResponse>;
+    /**
+     * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
+     *
+     * 브라우저에서 `<input type="file">` 로 받은 `File` 또는 `Blob` 을 그대로 넘기면 SDK 가
+     * base64 로 인코딩 + MIME 추정 후 서버에 보낸다. 서버는 PDF / DOCX / text 류를 자동
+     * 텍스트 추출하여 기존 청킹·인덱싱 파이프라인을 태운다.
+     *
+     * 지원 MIME (2026-05 기준):
+     *   - `application/pdf` (텍스트 PDF — 스캔 이미지 PDF 는 미지원)
+     *   - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (DOCX)
+     *   - `text/*` (plain / markdown / csv / html)
+     *   - `application/json`
+     *
+     * 비지원 MIME (이미지 OCR / 한글 HWP / XLSX 등) 은 향후 추가될 예정 — 현재는 명시적 에러.
+     *
+     * 파일 크기 상한: 50MB (원본 바이너리 기준).
+     *
+     * @param kbID - Knowledge Base ID
+     * @param file - 업로드할 파일. `File` (DOM) / `Blob` / `{ data, mimeType, name }` (Node) 모두 가능
+     * @param options - name 오버라이드 + metadata
+     * @returns 생성된 문서 정보 (서버에서 status='processing' → 청킹 완료 후 'ready')
+     *
+     * @example
+     * ```typescript
+     * // 브라우저: <input type="file"> 로 받은 File
+     * const file = event.target.files[0]
+     * const doc = await cb.knowledge.addDocumentFromFile('kb-id', file, {
+     *     metadata: { tag: 'manual' }
+     * })
+     *
+     * // Node.js: fs.readFileSync 로 읽은 Buffer
+     * import { readFileSync } from 'node:fs'
+     * const data = readFileSync('./report.pdf')
+     * const doc = await cb.knowledge.addDocumentFromFile('kb-id', {
+     *     data,
+     *     mimeType: 'application/pdf',
+     *     name: 'report.pdf',
+     * })
+     * ```
+     */
+    addDocumentFromFile(kbID: string, file: KnowledgeFileInput, options?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<DocumentResponse>;
+    /**
+     * 문서 목록 조회
+     *
+     * @param kbID - 지식 베이스 ID
+     * @returns 문서 목록
+     */
+    listDocuments(kbID: string): Promise<ListDocumentsResponse>;
+    /**
+     * 문서 삭제
+     *
+     * 문서와 관련된 모든 청크도 함께 삭제됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param docID - 문서 ID
+     */
+    deleteDocument(kbID: string, docID: string): Promise<void>;
+    /**
+     * 문서 검색
+     *
+     * 키워드 기반으로 관련 문서 청크를 검색합니다.
+     * 제목, 내용, 키워드 필드에서 매칭되며 점수 기반으로 정렬됩니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param request - 검색 요청
+     * @returns 검색 결과
+     *
+     * @example
+     * ```typescript
+     * const results = await cb.knowledge.search('kb-id', {
+     *     query: '환불 신청 방법',
+     *     top_k: 5  // 상위 5개 결과
+     * })
+     *
+     * for (const result of results.results) {
+     *     console.log(`[${result.score}] ${result.title}`)
+     *     console.log(result.content)
+     * }
+     * ```
+     */
+    search(kbID: string, request: KnowledgeSearchRequest): Promise<KnowledgeSearchResponse>;
+    /**
+     * 문서 검색 (GET 방식)
+     *
+     * 쿼리 파라미터로 검색합니다.
+     *
+     * @param kbID - 지식 베이스 ID
+     * @param query - 검색 쿼리
+     * @param topK - 반환할 결과 수 (기본값: 지식 베이스 설정)
+     */
+    searchGet(kbID: string, query: string, topK?: number): Promise<KnowledgeSearchResponse>;
+}
+
+interface AIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: AIToolCall[];
+    toolCallId?: string;
+}
+interface AIToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+interface AITool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface AIChatRequest {
+    messages: AIMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    provider?: string;
+    model?: string;
+    tools?: AITool[];
+    appId?: string;
+    knowledgeBaseId?: string;
+    topK?: number;
+    agentic?: boolean;
+    toolGroupId?: string;
+}
+interface AIToolEvent {
+    type: 'tool_start' | 'tool_end' | 'heartbeat';
+    name?: string;
+    toolCallId?: string;
+    arguments?: Record<string, unknown>;
+    result?: string;
+    success?: boolean;
+    durationMs?: number;
+}
+interface AISource {
+    chunkId: string;
+    documentId: string;
+    documentName: string;
+    content: string;
+    score: number;
+}
+interface AIChatResponse {
+    content: string;
+    /**
+     * 추론 모델(Qwen3 reasoning, OpenAI o-series, DeepSeek-R1 등)의 사고 과정.
+     * 최종 답변(`content`)과 분리되어 제공됩니다. 추론 모델이 아니면 비어 있습니다.
+     */
+    reasoning?: string;
+    finishReason?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    provider: string;
+    model: string;
+    toolCalls?: AIToolCall[];
+    sources?: AISource[];
+}
+/**
+ * Agentic 검색의 한 단계 진행 상황. `chatStream({ agentic: true })` 시
+ * `onSearching` 콜백으로 실시간 전달되어 "검색 중…" 진행 UI 를 구성할 수 있다.
+ */
+interface AgenticSearchProgress {
+    /** 'query_generation' = 검색어 생성 중, 'searching' = 검색 실행 중, 'complete' = 검색 종료 */
+    phase: 'query_generation' | 'searching' | 'complete';
+    /** 검색 라운드 (1~2). agentic 은 결과가 부족하면 2라운드까지 수행. */
+    round?: number;
+    /** 이 라운드에서 생성된 검색 쿼리들 (phase='searching'). */
+    queries?: string[];
+    /** phase='complete': 누적 결과 청크 수. */
+    results?: number;
+    /** phase='complete': 총 검색 라운드 수. 0 은 폴백(단일 키워드 검색)을 의미. */
+    rounds?: number;
+}
+interface AIStreamChunk {
+    type?: 'sources' | 'token' | 'searching' | 'tool_start' | 'tool_end' | 'heartbeat';
+    content: string;
+    /**
+     * 추론 모델의 사고 과정 델타. 추론 구간의 청크는 `content`가 비어 있고
+     * `reasoning`만 채워져 전달됩니다.
+     */
+    reasoning?: string;
+    finishReason?: string;
+    done: boolean;
+    toolCalls?: AIToolCall[];
+    sources?: AISource[];
+    name?: string;
+    toolCallId?: string;
+    arguments?: Record<string, unknown>;
+    result?: string;
+    success?: boolean;
+    durationMs?: number;
+    searching?: AgenticSearchProgress;
+}
+
+/**
+ * AI API
+ *
+ * AI 채팅 및 AI 데이터베이스 연동 API.
+ * AI 데이터베이스 ID를 지정하면 문서 검색 후 컨텍스트를 포함하여 응답합니다.
+ *
+ * @example
+ * ```typescript
+ * const cb = new ConnectBase({ publicKey: 'your-public-key' })
+ *
+ * // 일반 AI 채팅
+ * const response = await cb.ai.chat({
+ *     messages: [{ role: 'user', content: '안녕하세요' }],
+ *     provider: 'gemini'
+ * })
+ *
+ * // AI 데이터베이스 연동 채팅
+ * const ragResponse = await cb.ai.chat({
+ *     messages: [{ role: 'user', content: '환불 정책이 어떻게 되나요?' }],
+ *     knowledgeBaseId: 'kb-id',
+ *     topK: 5
+ * })
+ * ```
+ */
+declare class AIAPI {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * AI 채팅 (동기)
+     */
+    chat(request: AIChatRequest): Promise<AIChatResponse>;
+    /**
+     * AI 채팅 스트리밍 (SSE)
+     *
+     * @example
+     * ```typescript
+     * await cb.ai.chatStream({
+     *     messages: [{ role: 'user', content: '안녕하세요' }],
+     *     knowledgeBaseId: 'kb-id',
+     * }, {
+     *     onSources: (sources) => console.log('참조:', sources),
+     *     onReasoning: (reasoning) => process.stdout.write(reasoning),
+     *     onToken: (content) => process.stdout.write(content),
+     *     onDone: () => console.log('\\n완료'),
+     *     onError: (error) => console.error('에러:', error)
+     * })
+     * ```
+     */
+    chatStream(request: AIChatRequest, callbacks: {
+        onSources?: (sources: AISource[]) => void;
+        /**
+         * 추론 모델의 사고 과정 델타. 추론 모델(Qwen3 reasoning, o-series 등)을
+         * 사용할 때만 호출되며, 최종 답변은 `onToken`으로 별도 전달됩니다.
+         */
+        onReasoning?: (reasoning: string) => void;
+        onToken?: (content: string) => void;
+        onToolEvent?: (event: AIToolEvent) => void;
+        /**
+         * Agentic 검색(`agentic: true`) 진행 상황. agentic 검색이 검색어를
+         * 생성하고 다중 라운드로 검색하는 각 단계마다 호출되어, "검색 중…"
+         * 진행 UI 를 구성할 수 있다. agentic 미사용 시 호출되지 않는다.
+         */
+        onSearching?: (progress: AgenticSearchProgress) => void;
+        onDone?: () => void;
+        onError?: (error: string) => void;
+    }): Promise<void>;
+}
+
+/**
+ * EndpointAPI — 사용자 PC GPU 모델을 `cb_pk_*` 한 키로 호출하는 dumb pipe.
+ *
+ * 핵심 비전: ConnectBase 는 **모델·API·워크플로우를 알지 않는다**. 사용자가 자기 PC 에서
+ * 자기 모델을 띄우고 자기 API 를 정한다. SDK 는 라벨 → tunnel 매핑만 알고 페이로드
+ * 그대로 forward.
+ *
+ * @example ComfyUI 호출
+ * ```typescript
+ * const cb = new ConnectBase({ publicKey: "cb_pk_..." })
+ * const res = await cb.endpoint.call("comfyui-main", {
+ *     method: "POST",
+ *     path: "/prompt",
+ *     body: JSON.stringify({
+ *         prompt: {
+ *             // ComfyUI 노드 그래프
+ *         },
+ *     }),
+ *     headers: { "Content-Type": "application/json" },
+ * })
+ * const data = await res.json()
+ * ```
+ *
+ * @example 스트리밍 응답 (SSE / chunked)
+ * ```typescript
+ * const res = await cb.endpoint.call("vllm-local", {
+ *     method: "POST",
+ *     path: "/v1/chat/completions",
+ *     body: JSON.stringify({
+ *         stream: true,
+ *         messages: [
+ *             // { role, content }
+ *         ],
+ *     }),
+ *     headers: { "Content-Type": "application/json" },
+ * })
+ * if (!res.body) throw new Error("no stream")
+ * const reader = res.body.getReader()
+ * while (true) {
+ *     const { done, value } = await reader.read()
+ *     if (done) break
+ *     // value 는 Uint8Array — 디코드 후 처리
+ * }
+ * ```
+ *
+ * @example AbortSignal 으로 취소
+ * ```typescript
+ * const ctrl = new AbortController()
+ * setTimeout(() => ctrl.abort(), 30_000) // 30초 후 취소
+ * const res = await cb.endpoint.call("hunyuan-laptop", {
+ *     method: "POST",
+ *     path: "/generate",
+ *     signal: ctrl.signal,
+ *     body: JSON.stringify({
+ *         // 모델 입력
+ *     }),
  * })
  * ```
  */
-declare class KnowledgeAPI {
+declare class EndpointAPI {
     private http;
     constructor(http: HttpClient);
     /**
-     * 문서 추가
+     * 라벨 + path 로 사용자 PC 모델 호출. fetch() 시그니처 호환.
      *
-     * 지식 베이스에 새 문서를 추가합니다. 텍스트 소스인 경우 즉시 처리됩니다.
+     * 동작:
+     *  - URL 조립: `${baseUrl}/v1/proxy/${label}${path}`
+     *  - X-Public-Key 헤더 자동 주입 (호출자가 명시하면 그 값 우선)
+     *  - body / method / 추가 헤더 / signal 그대로 전달
+     *  - 응답 그대로 반환 (Response 객체) — 스트리밍은 res.body 로 read
      *
-     * @param kbID - 지식 베이스 ID
-     * @param data - 문서 생성 요청
-     * @returns 생성된 문서 정보
+     * @param label - 콘솔에서 등록한 endpoint 라벨 (예: "comfyui-main")
+     * @param init - fetch() 의 RequestInit + path. path 는 사용자 모델 서버의 엔드포인트 경로 (예: "/prompt", "/v1/chat/completions").
+     */
+    call(label: string, init: EndpointCallInit): Promise<Response>;
+    /**
+     * 라벨 + path 의 최종 호출 URL `${baseUrl}/v1/proxy/${label}${path}` 을 조립해서
+     * 반환. URL 을 다른 시스템 (Service Worker, 백엔드 워커, 로깅) 에 넘기거나
+     * 디버깅 용도일 때 사용.
      *
-     * @example
+     * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
+     * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
+     * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
+     * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
+     *
+     * @example URL 을 워커로 넘겨 호출 (✅)
      * ```typescript
-     * // 텍스트 문서
-     * const doc = await cb.knowledge.addDocument('kb-id', {
-     *     name: 'FAQ',
-     *     source_type: 'text',
-     *     content: '자주 묻는 질문들...'
+     * sw.postMessage({
+     *     url: cb.endpoint.url("comfyui-main", "/prompt"),
+     *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
      * })
+     * ```
      *
-     * // URL에서 가져오기
-     * const doc2 = await cb.knowledge.addDocument('kb-id', {
-     *     name: '도움말',
-     *     source_type: 'url',
-     *     source_url: 'https://example.com/help.html'
+     * @example 이미지 렌더링은 call() + Blob URL 패턴으로 (✅)
+     * ```typescript
+     * const res = await cb.endpoint.call("comfyui-main", {
+     *     path: `/view?filename=${encodeURIComponent(name)}`,
      * })
+     * img.src = URL.createObjectURL(await res.blob())
+     * // 나중에 URL.revokeObjectURL(img.src)
      * ```
      */
-    addDocument(kbID: string, data: CreateDocumentRequest): Promise<DocumentResponse>;
+    url(label: string, path: string): string;
     /**
-     * 문서 목록 조회
+     * 같은 endpoint 호출을 `predicate` 가 값을 반환할 때까지 주기적으로 반복.
+     * ComfyUI `/history/{id}`, A1111 `/sdapi/v1/progress`, 자체 큐 API 처럼
+     * "작업 제출 → 폴링" 패턴을 한 줄로 처리하기 위한 헬퍼.
      *
-     * @param kbID - 지식 베이스 ID
-     * @returns 문서 목록
-     */
-    listDocuments(kbID: string): Promise<ListDocumentsResponse>;
-    /**
-     * 문서 삭제
+     * 동작:
+     *  - `call(label, init)` → predicate(response) 호출
+     *  - predicate 가 `undefined` 면 `intervalMs` 만큼 대기 후 재시도
+     *  - predicate 가 값을 반환하면 그 값을 즉시 resolve
+     *  - `timeoutMs` 초과 또는 `signal` abort 시 reject
+     *  - HTTP 5xx/네트워크 오류는 재시도, 4xx 는 즉시 reject (작업 자체가 잘못된 경우)
      *
-     * 문서와 관련된 모든 청크도 함께 삭제됩니다.
+     * predicate 는 같은 Response 를 한 번만 읽을 수 있으므로, 헬퍼 내부에서
+     * `res.clone().json()` 형태로 안전하게 파싱한 뒤 호출자에게 전달.
      *
-     * @param kbID - 지식 베이스 ID
-     * @param docID - 문서 ID
+     * @example ComfyUI 결과 폴링
+     * ```typescript
+     * type Hist = Record<string, { outputs: Record<string, { images?: { filename: string }[] }> }>
+     *
+     * const filename = await cb.endpoint.pollUntil<string>(
+     *     "comfyui-main",
+     *     { path: `/history/${promptId}` },
+     *     (data: Hist) => {
+     *         const entry = data[promptId]
+     *         if (!entry) return undefined // 아직 큐에 있음
+     *         for (const out of Object.values(entry.outputs)) {
+     *             const img = out.images?.[0]
+     *             if (img) return img.filename
+     *         }
+     *         return undefined
+     *     },
+     *     { intervalMs: 1000, timeoutMs: 5 * 60_000 },
+     * )
+     * ```
      */
-    deleteDocument(kbID: string, docID: string): Promise<void>;
     /**
-     * 문서 검색
+     * Open a native browser `WebSocket` to a user model server (e.g. ComfyUI's
+     * `/ws` event channel) through the ConnectBase proxy.
      *
-     * 키워드 기반으로 관련 문서 청크를 검색합니다.
-     * 제목, 내용, 키워드 필드에서 매칭되며 점수 기반으로 정렬됩니다.
+     * Background: native browser `WebSocket` cannot send custom headers, so
+     * `X-Public-Key` cannot be supplied on the Upgrade request. This helper
+     * solves that by:
+     *   1. POSTing to `/v1/proxy/<label>/ws-ticket` (with `X-Public-Key`)
+     *      to obtain a single-use 30s token,
+     *   2. Opening `wss://<base>/v1/proxy/<label><path>?ticket=<token>&...`,
+     *   3. Returning the established `WebSocket` to the caller.
      *
-     * @param kbID - 지식 베이스 ID
-     * @param request - 검색 요청
-     * @returns 검색 결과
+     * Both the client→upstream and upstream→client byte streams flow
+     * transparently — the proxy server adds no framing of its own.
      *
-     * @example
-     * ```typescript
-     * const results = await cb.knowledge.search('kb-id', {
-     *     query: '환불 신청 방법',
-     *     top_k: 5  // 상위 5개 결과
+     * @example ComfyUI native event channel
+     * ```ts
+     * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
+     *     path: "/ws",
+     *     query: { clientId: crypto.randomUUID() },
      * })
-     *
-     * for (const result of results.results) {
-     *     console.log(`[${result.score}] ${result.title}`)
-     *     console.log(result.content)
+     * ws.onmessage = (e) => {
+     *     const msg = JSON.parse(typeof e.data === "string" ? e.data : "")
+     *     if (msg.type === "progress") {
+     *         // progress.value / progress.max — exact node-level progress
+     *     }
      * }
      * ```
      */
-    search(kbID: string, request: KnowledgeSearchRequest): Promise<KnowledgeSearchResponse>;
+    connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
+    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: any, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
+}
+/**
+ * EndpointAPI.call 의 init 인자.
+ *
+ * 표준 RequestInit 와 거의 동일하지만 `path` 가 필수 (URL 은 SDK 가 조립).
+ */
+interface EndpointCallInit {
     /**
-     * 문서 검색 (GET 방식)
-     *
-     * 쿼리 파라미터로 검색합니다.
-     *
-     * @param kbID - 지식 베이스 ID
-     * @param query - 검색 쿼리
-     * @param topK - 반환할 결과 수 (기본값: 지식 베이스 설정)
+     * 사용자 모델 서버의 엔드포인트 경로. 반드시 `/` 로 시작.
+     * 예: `"/prompt"`, `"/v1/chat/completions"`, `"/sdapi/v1/txt2img"`.
      */
-    searchGet(kbID: string, query: string, topK?: number): Promise<KnowledgeSearchResponse>;
+    path: string;
+    /** HTTP 메서드 (기본: GET). */
+    method?: string;
+    /** 추가 요청 헤더. Content-Type / Authorization 등 사용자 모델 서버가 요구하는 것 그대로. */
+    headers?: HeadersInit;
+    /** 요청 본문. Blob / ArrayBuffer / FormData / string / ReadableStream 모두 지원. */
+    body?: BodyInit | null;
+    /** 취소 신호. */
+    signal?: AbortSignal;
+}
+/**
+ * EndpointAPI.connectWebSocket 옵션.
+ */
+interface ConnectWebSocketOptions {
+    /**
+     * 사용자 모델 서버의 WebSocket 엔드포인트 경로. `/` 로 시작 (기본 `/`).
+     * 예: `/ws`, `/socket`.
+     */
+    path?: string;
+    /** 추가 query 파라미터 (ticket 은 자동 주입). */
+    query?: Record<string, string>;
+    /** WebSocket subprotocols (Sec-WebSocket-Protocol 헤더). */
+    protocols?: string | string[];
+    /** Abort 시 ws.close(1000) 호출. */
+    signal?: AbortSignal;
+}
+/**
+ * EndpointAPI.pollUntil 옵션.
+ */
+interface PollUntilOptions {
+    /** 폴링 간격 (ms). 기본 1500. */
+    intervalMs?: number;
+    /** 전체 timeout (ms). 기본 300000 (5분). */
+    timeoutMs?: number;
+    /**
+     * 응답 본문 파싱 방식.
+     *  - `"json"` (기본) — `res.json()`. 파싱 실패 시 predicate 에 `undefined` 전달.
+     *  - `"text"` — 문자열 그대로.
+     *  - `"none"` — 본문 사용 안 함 (예: 헤더 / status 만 보고 판단).
+     */
+    parse?: "json" | "text" | "none";
+    /** 외부 취소 신호. abort 시 즉시 reject. */
+    signal?: AbortSignal;
 }
 
 interface PublishMessageRequest {
@@ -5389,7 +7851,7 @@ interface QueueInfoResponse {
  *
  * @example
  * ```typescript
- * const cb = new ConnectBase({ apiKey: 'your-api-key' })
+ * const cb = new ConnectBase({ publicKey: 'your-public-key' })
  *
  * // 메시지 발행
  * await cb.queue.publish('queue-id', {
@@ -5438,6 +7900,334 @@ declare class QueueAPI {
     getInfo(queueID: string): Promise<QueueInfoResponse>;
 }
 
+/**
+ * 사용자 제보 (end-user issue) — 카테고리.
+ *
+ * - `bug` 버그 리포트
+ * - `question` 질문/문의
+ * - `feature_request` 기능 요청
+ * - `incident` 긴급 장애
+ * - `other` 그 외
+ */
+type SupportIssueCategory = 'bug' | 'question' | 'feature_request' | 'incident' | 'other';
+/**
+ * 제보 발행 요청 본문.
+ */
+interface ReportIssueRequest {
+    /** 제목 (최대 200자) */
+    title: string;
+    /** 본문 (최대 16KB, 마크다운) */
+    body: string;
+    /** 카테고리. 기본값 `other`. AI 가 자동 보정해 줌. */
+    category?: SupportIssueCategory;
+    /** 자유 컨텍스트 (페이지 URL, 앱 버전, trace_id 등) */
+    metadata?: Record<string, unknown>;
+    /**
+     * 익명 발행 시 회신 받을 이메일 (선택).
+     * 로그인된 사용자면 무시되고 AppMember 정보로 대체.
+     */
+    anonymousEmail?: string;
+    /**
+     * Google reCAPTCHA v3 토큰. 익명 발행 + 운영자가 reCAPTCHA 활성화한 앱은 권장.
+     * 미주입 시 score=0 으로 처리 — 거부될 수 있음.
+     */
+    recaptchaToken?: string;
+}
+/**
+ * 제보 발행 응답. 보안상 최소 정보만 (id + status + created_at).
+ */
+interface ReportIssueResponse {
+    id: string;
+    status: 'open';
+    created_at: string;
+}
+/**
+ * Cross-app 위임 user 발행 요청 본문.
+ *
+ * 일반 `reportIssue` 와 다른 점:
+ *   - target_app 이 호출자(source_app) 와 다름 (다른 앱에 보내는 위임 제보)
+ *   - SDK 인증 컨텍스트(publicKey/secretKey) 가 아닌 cross-app OAuth Bearer access_token 사용
+ *   - reporter_member_id 는 access_token 의 end_user_id claim 에서 자동 추출 (body 로 전달 불가)
+ */
+interface ReportIssueOnBehalfOfUserRequest {
+    /** 수신 앱(target) 의 ID. OAuth token 의 audience(`app:<uuid>`) 와 일치해야 함. */
+    targetAppId: string;
+    /**
+     * Cross-app OAuth access_token (`authorization_code` grant — user binding 필수).
+     * scope 에 `issue:report:on-behalf-of-user` 가 포함돼야 한다.
+     * `client_credentials` grant 토큰은 401 `delegated_user_required` 로 거부됨.
+     */
+    accessToken: string;
+    /** 제목 (최대 200자) */
+    title: string;
+    /** 본문 (최대 16KB, 마크다운) */
+    body: string;
+    /** 카테고리. 기본값 `other`. AI triage 가 보정. */
+    category?: SupportIssueCategory;
+    /** 자유 컨텍스트 (페이지 URL, request_id 등). PII 직접 포함 금지. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Support API — 사용자 제보 (end-user issue) 발행.
+ *
+ * 사용자가 앱 운영자에게 직접 버그/질문/요청을 보내는 채널. AppMember JWT 가 있으면
+ * 강 신뢰로 회신 가능, 없으면 익명 발행 (reCAPTCHA 권장).
+ *
+ * 발행된 이슈는 운영자 콘솔의 inbox 에 들어가며, AI 가 자동으로 요약/긴급도/카테고리를
+ * 분류해줘 운영자/AI 의 처리 효율을 높여준다.
+ *
+ * @example 로그인 사용자가 버그 리포트
+ * ```typescript
+ * // (cb.auth.signIn 으로 로그인 완료된 상태)
+ * await cb.support.reportIssue({
+ *     title: "결제 화면이 멈춰요",
+ *     body: "결제 버튼 클릭 후 로딩이 끝나지 않습니다.",
+ *     category: "bug",
+ *     metadata: { pageUrl: window.location.href, browser: navigator.userAgent },
+ * })
+ * ```
+ *
+ * @example 익명 + reCAPTCHA v3
+ * ```typescript
+ * // window.grecaptcha 는 reCAPTCHA v3 site script 로드 후 전역으로 노출됨
+ * const grecaptcha = (globalThis as any).grecaptcha
+ * const SITE_KEY = "your-recaptcha-site-key"
+ * const token = await grecaptcha.execute(SITE_KEY, { action: 'report_issue' })
+ * await cb.support.reportIssue({
+ *     title: "버그 제보",
+ *     body: "익명으로 제보합니다",
+ *     category: "question",
+ *     anonymousEmail: "user@example.com",
+ *     recaptchaToken: token,
+ * })
+ * ```
+ */
+declare class SupportAPI {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * 앱 운영자에게 이슈/문의/요청을 발행한다.
+     *
+     * 로그인된 사용자(AppMember)면 신뢰 등급이 높고 reporter_member_id 가 자동으로 채워진다.
+     * 익명 발행도 가능하나 운영자가 reCAPTCHA 를 활성화한 경우 `recaptchaToken` 이 권장된다.
+     *
+     * @returns 발행된 이슈 id + 초기 status (`open`) + 생성 시각.
+     * @throws ApiError — 본문 길이 초과 / 쿼터 초과(429) / reCAPTCHA 거부(403) 등.
+     */
+    reportIssue(req: ReportIssueRequest): Promise<ReportIssueResponse>;
+    /**
+     * 다른 앱(target) 에 자기 사용자(end-user) 명의로 cross-app 위임 이슈를 발행한다.
+     *
+     * **사용 시나리오**: source_app(예: Makers) 의 backend 가 OAuth `authorization_code` grant 로
+     * 발급받은 사용자 access_token 을 사용해, target_app(예: ai-tool) 에게 "Makers user A 가 보낸"
+     * 이슈로 제보. target 측 콘솔 inbox 에는 `reporter_kind=user` + `reporter_app_id=Makers` 로 표시.
+     *
+     * 본 메서드는 SDK 의 publicKey/secretKey 인증 컨텍스트를 사용하지 않고, 호출자가 명시적으로 전달한
+     * cross-app OAuth Bearer access_token 만 사용 (server-to-server 위임 흐름).
+     *
+     * @param req - 발행 본문
+     * @param req.targetAppId - 수신 앱 ID (= OAuth token 의 audience `app:<uuid>` 와 일치해야 함)
+     * @param req.accessToken - source_app 이 발급받은 cross-app OAuth access_token (authorization_code grant)
+     *
+     * @throws ApiError 401 — `delegated_user_required`: access_token 이 client_credentials grant
+     * @throws ApiError 403 — `trust_chain_violation`: source_app 이 target_app 의 cross-app provider 로 등록되지 않음
+     * @throws ApiError 403 — `insufficient_scope`: token 에 `issue:report:on-behalf-of-user` 미포함
+     *
+     * @example Makers backend → ai-tool 에 사용자 명의 제보
+     * ```typescript
+     * await cb.support.reportIssueOnBehalfOfUser({
+     *     targetAppId: 'ai-tool-uuid',
+     *     accessToken: makersUserAccessToken, // authorization_code grant 토큰
+     *     title: '생성 실패',
+     *     body: 'prompt X 가 5분째 응답 없음',
+     *     category: 'bug',
+     *     metadata: { prompt_id: 'p_42' },
+     * })
+     * ```
+     */
+    reportIssueOnBehalfOfUser(req: ReportIssueOnBehalfOfUserRequest): Promise<ReportIssueResponse>;
+    /**
+     * ConnectBase 플랫폼 자체 버그/요청/문의를 발행한다.
+     *
+     * `reportIssue` 와 다른 점: target 이 앱 운영자가 아닌 **ConnectBase 운영팀**.
+     * SDK 가 자체 버그를 던지거나, 결제/문서/플랫폼 동작이 이상할 때 사용.
+     *
+     * 자동 첨부 (opt-out 가능):
+     *   - SDK 버전 + 플랫폼 (web/node)
+     *   - 마지막 N(20)개 API 호출 breadcrumb (PII strip 후)
+     *   - error 객체의 stack trace (sanitize)
+     *
+     * @example SDK 가 throw 한 에러를 자동 첨부해서 발행
+     * ```typescript
+     * try {
+     *   await cb.functions.invoke('foo', {})
+     * } catch (err) {
+     *   await cb.support.reportPlatformBug({
+     *     title: 'functions.invoke 가 504 만 반환',
+     *     body: '같은 인자로 5분 째 504. 콘솔에선 정상.',
+     *     category: 'sdk',
+     *     severity: 'high',
+     *     error: err as Error,
+     *   })
+     * }
+     * ```
+     */
+    reportPlatformBug(req: ReportPlatformBugRequest): Promise<ReportPlatformBugResponse>;
+    /** 디버깅용: 마지막 N개 API 호출 breadcrumb. PII 제거 후 저장돼있다. */
+    getRecentApiCalls(): RecentApiCall[];
+    /** breadcrumb buffer 비우기 (사용자 명시적 요청 / 프라이버시). */
+    clearRecentApiCalls(): void;
+    /**
+     * Platform issue 의 reply thread 조회.
+     *
+     * 본인이 발행한 issue 만 조회 가능 (server-side ownership guard). admin 의 internal 메모는 응답 제외.
+     *
+     * @param issueId - `reportPlatformBug` 가 반환한 id
+     * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+     */
+    listPlatformIssueReplies(issueId: string): Promise<PlatformIssueReply[]>;
+    /**
+     * Platform issue 에 follow-up reply 작성.
+     *
+     * 단말 상태(resolved/wontfix/duplicate) issue 는 reply 거부 — 새 issue 발행 권장.
+     */
+    replyToPlatformIssue(issueId: string, body: string): Promise<PlatformIssueReply>;
+    /**
+     * 본인이 발행한 platform issue 의 처리 진행 상황을 단건 조회.
+     *
+     * AI 가 "내가 발행한 이슈 처리됐어?" 를 폴링하는 표준 경로. status / resolution_note /
+     * external_links 로 ConnectBase 운영팀의 처리 상태를 확인.
+     *
+     * @throws ApiError 404 — 본인 issue 가 아니거나 존재하지 않음
+     */
+    getPlatformIssue(issueId: string): Promise<PlatformIssueDetail>;
+    /**
+     * 본인 app 으로 발행한 platform issue 목록 (cursor 페이지네이션).
+     *
+     * status/severity/category 필터 + `since_updated_at` 으로 미해결만 폴링하는 사용 패턴 권장:
+     *
+     * ```typescript
+     * const { issues } = await cb.support.listMyPlatformIssues({ status: ['open', 'triaged', 'in_progress'] })
+     * ```
+     */
+    listMyPlatformIssues(opts?: ListMyPlatformIssuesOptions): Promise<PlatformIssueListPage>;
+}
+/**
+ * ConnectBase 플랫폼 이슈 카테고리.
+ */
+type PlatformIssueCategory = 'bug' | 'feature_request' | 'sdk' | 'billing' | 'security' | 'performance' | 'docs' | 'other';
+type PlatformIssueSeverity = 'low' | 'medium' | 'high' | 'critical';
+interface ReportPlatformBugRequest {
+    /** 제목 (≤200) */
+    title: string;
+    /** 본문 (≤16KB, markdown) */
+    body: string;
+    /** 카테고리. 기본 `other`. 운영자가 admin 콘솔에서 조정 가능. */
+    category?: PlatformIssueCategory;
+    /** 긴급도. 기본 `medium`. 운영자가 admin 콘솔에서 조정 가능. */
+    severity?: PlatformIssueSeverity;
+    /** AppMember 가 없는 경우 회신용 이메일. */
+    reporterEmail?: string;
+    /** 익명 발행 시 reCAPTCHA v3 토큰 (운영팀이 RECAPTCHA_SECRET 설정한 경우). */
+    recaptchaToken?: string;
+    /** 자유 컨텍스트 (페이지 URL, request_id 등). PII 직접 포함 금지 — 호출자 책임. */
+    metadata?: Record<string, unknown>;
+    /**
+     * 자동 컨텍스트 첨부 on/off (기본 true).
+     * false 로 설정하면 SDK 버전/플랫폼/breadcrumb/stack 모두 미첨부.
+     */
+    attachAutomaticContext?: boolean;
+    /**
+     * 에러 객체. .stack 을 sanitize 후 자동 첨부.
+     * stackTrace 와 둘 중 하나만 — error 가 우선.
+     */
+    error?: Error;
+    /** 직접 작성한 stack trace (≤32KB, SDK 가 sanitize). */
+    stackTrace?: string;
+    /** 호출자가 명시적으로 buffer 를 override (테스트/특수 케이스). */
+    recentApiCalls?: RecentApiCall[];
+    /** SDK 버전 override (자동 감지 실패 시). */
+    sdkVersion?: string;
+    /** SDK 플랫폼 override. */
+    sdkPlatform?: 'web' | 'node' | 'unity' | 'godot' | 'unreal' | 'cli' | 'mcp' | 'other';
+    /** 환경 (production/staging/development). 기본 unknown. */
+    environment?: 'production' | 'staging' | 'development' | 'unknown';
+}
+interface ReportPlatformBugResponse {
+    id: string;
+    status: 'open';
+    created_at: string;
+}
+/**
+ * Platform issue thread 의 단일 reply.
+ *
+ * - `author_kind=admin`: ConnectBase 운영팀 응답
+ * - `author_kind=user`: 본인이 작성
+ * - `author_kind=system`: 자동 메시지 (상태 변경 알림 등)
+ */
+/**
+ * Platform issue 의 처리 진행 상황 (reporter 시점).
+ *
+ * admin-only 필드(`assignee_user_id` 등) 는 server 가 redact.
+ *
+ * 주요 필드:
+ *   - `status`           : `open` → `triaged` → `in_progress` → `resolved` | `wontfix` | `duplicate`
+ *   - `resolution_note`  : 단말 상태 진입 시 ConnectBase 운영팀이 작성한 처리 결과 (markdown)
+ *   - `external_links`   : 운영팀이 연결한 GitHub PR / Linear ticket 등
+ *   - `resolved_at`      : `resolved`/`wontfix` 진입 시각 (해결됐는지 빠른 검사용)
+ */
+interface PlatformIssueDetail {
+    id: string;
+    reporter_kind: 'user' | 'app' | 'system';
+    title: string;
+    body: string;
+    category: PlatformIssueCategory;
+    severity: PlatformIssueSeverity;
+    status: 'open' | 'triaged' | 'in_progress' | 'resolved' | 'wontfix' | 'duplicate';
+    resolution_note?: string;
+    sdk_version?: string;
+    sdk_platform?: 'web' | 'node' | 'unity' | 'godot' | 'unreal' | 'cli' | 'mcp' | 'other';
+    environment?: 'production' | 'staging' | 'development' | 'unknown';
+    external_links?: Array<{
+        kind: string;
+        url: string;
+        label?: string;
+    }>;
+    duplicate_of_id?: string;
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+/** `listMyPlatformIssues` 응답 페이지. */
+interface PlatformIssueListPage {
+    issues: PlatformIssueDetail[];
+    /** 다음 페이지 cursor. 빈 문자열/undefined 면 끝. */
+    next_cursor?: string;
+}
+/** `listMyPlatformIssues` 옵션. */
+interface ListMyPlatformIssuesOptions {
+    /** 다중 status 필터. 미지정 시 전체. 처리중만 보려면 `['open','triaged','in_progress']`. */
+    status?: PlatformIssueDetail['status'][];
+    severity?: PlatformIssueSeverity[];
+    category?: PlatformIssueCategory[];
+    /** RFC3339 timestamp — 이후 update 된 issue 만. polling 시 마지막 fetch 시각 전달. */
+    sinceUpdatedAt?: string;
+    /** 이전 페이지 응답의 `next_cursor`. */
+    cursor?: string;
+    /** 페이지 크기. 기본 50, 최대 200. */
+    limit?: number;
+}
+interface PlatformIssueReply {
+    id: string;
+    issue_id: string;
+    author_kind: 'admin' | 'user' | 'system';
+    author_user_id?: string;
+    author_member_id?: string;
+    body: string;
+    is_internal: boolean;
+    created_at: string;
+}
+
 /**
  * WebTransport-based Game Client
  *
@@ -5484,6 +8274,8 @@ declare class GameRoomTransport {
     private actionSequence;
     private _roomId;
     private _state;
+    private _scriptName;
+    private _scriptVersion;
     private _isConnected;
     private _connectionStatus;
     private _lastError;
@@ -5510,6 +8302,10 @@ declare class GameRoomTransport {
      * Connection status
      */
     get isConnected(): boolean;
+    /** Attached lua script 이름 — createRoom 이후 server 가 echo 한 값. */
+    get scriptName(): string | null;
+    /** Attached lua script 의 active version. */
+    get scriptVersion(): number | null;
     /**
      * Connection state information
      */
@@ -5531,9 +8327,16 @@ declare class GameRoomTransport {
      */
     disconnect(): void;
     /**
-     * Create a new room
+     * Create a new room (호환 시그니처) — 초기 상태만 반환.
+     *
+     * Attached script 메타가 필요하면 {@link createRoomDetailed} 또는 인스턴스 getter
+     * (`transport.scriptName`, `transport.scriptVersion`) 를 사용.
      */
     createRoom(config?: GameRoomConfig): Promise<GameState>;
+    /**
+     * Create a new room — server 가 attach 한 lua script 메타 함께 반환.
+     */
+    createRoomDetailed(config?: GameRoomConfig): Promise<CreateRoomResult>;
     /**
      * Join an existing room
      */
@@ -5606,9 +8409,21 @@ interface ConnectBaseConfig {
      */
     appId?: string;
     /**
-     * API Key (콘솔에서 발급)
+     * Public Key (cb_pk_* 형식, 콘솔 → 설정 → API 에서 발급)
+     * 브라우저/클라이언트에서 사용. RLS(Row Level Security) 적용.
+     */
+    publicKey?: string;
+    /**
+     * User Secret Key (`cb_sk_*` 형식, 사용자 프로필에서 발급).
+     *
+     * **SDK 의 앱 레벨 API (database, storage, function 등) 용 자격증명이 아닙니다.**
+     * 앱 API 호출에는 `publicKey` 를 사용하세요. 앱 API 경로(`/v1/public/*`)는
+     * Public Key(`cb_pk_*`) 만 허용하며, Secret Key 로 호출하면 서버가 401 을 반환합니다.
+     *
+     * 이 필드는 CLI (`connectbase tunnel`, `connectbase mcp`) 및 사용자 레벨 API 인증에
+     * 사용됩니다. 서버 환경에서만 사용하고 절대 브라우저에 노출하지 마세요.
      */
-    apiKey?: string;
+    secretKey?: string;
     /**
      * 토큰이 갱신될 때 호출되는 콜백
      */
@@ -5626,7 +8441,7 @@ interface ConnectBaseConfig {
      * @example
      * ```typescript
      * const cb = new ConnectBase({
-     *     apiKey: 'your-api-key',
+     *     publicKey: 'your-public-key',
      *     onTokenExpired: () => {
      *         // 로그인 페이지로 리다이렉트
      *         window.location.href = '/login'
@@ -5635,10 +8450,64 @@ interface ConnectBaseConfig {
      * ```
      */
     onTokenExpired?: () => void;
+    /**
+     * `/v1/auth/re-issue` 의 일시적 실패 (5xx, 네트워크 오류, abort, 손상된 200 응답) 시 호출.
+     *
+     * 이 경우 토큰은 폐기되지 않으며 `onTokenExpired` 도 호출되지 않습니다 — 다음 호출에서
+     * backoff 만료 후 자동 재시도. 사용자에게 "연결이 잠시 불안정합니다" 같은 비파괴적
+     * 알림을 띄울 때 사용. permanent (refresh token 자체 무효) 와 분리하기 위함.
+     *
+     * @example
+     * ```typescript
+     * const cb = new ConnectBase({
+     *     publicKey: '...',
+     *     onTransientRefreshFailure: (err) => toast.warn('연결이 불안정합니다. 잠시 후 자동 복구됩니다.'),
+     *     onTokenExpired: () => { window.location.href = '/login' },
+     * })
+     * ```
+     */
+    onTransientRefreshFailure?: (error: Error) => void;
+    /**
+     * 토큰 저장 방식.
+     * - 'none' (기본·권장): access token 만 메모리. refresh token 은 서버 HttpOnly cookie 로
+     *   보관되어 JS 가 접근할 수 없음 (XSS 시 탈취 불가). 새로고침 후에는 `autoRestoreSession`
+     *   (기본 true) 으로 cookie 만으로 자동 복구.
+     * - 'sessionStorage': 탭 종료 시 삭제 (XSS 시 탭 세션 탈취 가능 — 콘솔 경고 출력)
+     * - 'localStorage': 브라우저 종료 후에도 유지 (XSS 시 영구 탈취 가능 — 콘솔 경고 출력)
+     * @default 'none'
+     */
+    persistence?: TokenPersistence;
+    /**
+     * 새로고침/탭 재개 시 HttpOnly cookie 만으로 access token 을 자동 복구할지 여부.
+     * 브라우저 환경에서 기본 true. cookie 가 없거나 만료되었으면 조용히 실패.
+     *
+     * cookie 가 없는 미로그인 상태에서 콘솔에 401 노이즈가 찍히지 않도록 silent 처리한다.
+     *
+     * @default true (브라우저), false (Node.js / RN)
+     */
+    autoRestoreSession?: boolean;
     /**
      * 에러 트래커 설정
      */
     errorTracker?: ErrorTrackerConfig;
+    /**
+     * 기본 요청 타임아웃(ms). 개별 호출의 `timeout` 이 지정되면 해당 값이 우선.
+     * 기본값 30000ms. 0 또는 음수 지정 시 타임아웃 비활성화.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * 전역 에러 관찰자. 모든 `ApiError` / `AuthError` 발생 시 호출됩니다.
+     * Sentry/Datadog 등 관측성 파이프라인과 연결하기 위한 훅.
+     *
+     * @example
+     * ```ts
+     * const cb = new ConnectBase({
+     *   publicKey: '...',
+     *   onError: (err) => Sentry.captureException(err),
+     * })
+     * ```
+     */
+    onError?: (error: ApiError | AuthError) => void;
 }
 /**
  * Connect Base SDK
@@ -5649,13 +8518,13 @@ interface ConnectBaseConfig {
  *
  * // 간단 초기화 (API Key만 필요)
  * const cb = new ConnectBase({
- *     apiKey: 'your-api-key'
+ *     publicKey: 'your-public-key'
  * })
  *
  * // 커스텀 서버 URL 사용 시
  * const cb = new ConnectBase({
  *     baseUrl: 'https://your-server.com',
- *     apiKey: 'your-api-key'
+ *     publicKey: 'your-public-key'
  * })
  *
  * // 데이터 조회
@@ -5689,9 +8558,10 @@ declare class ConnectBase {
      */
     readonly storage: StorageAPI;
     /**
-     * API Key 관리 API
+     * Public Key 관리 API
      */
-    readonly apiKey: ApiKeyAPI;
+    readonly publicKey: PublicKeyAPI;
+    /**
     /**
      * 서버리스 함수 API
      */
@@ -5742,16 +8612,54 @@ declare class ConnectBase {
      */
     readonly native: NativeAPI;
     /**
-     * Knowledge Base API (RAG 문서 검색)
+     * AI 데이터베이스 API (문서 검색)
      * 문서를 업로드하고 키워드 기반으로 검색하여 AI 챗봇을 구축할 수 있습니다.
      */
     readonly knowledge: KnowledgeAPI;
+    /**
+     * AI API (채팅 + AI 데이터베이스 연동)
+     * AI 채팅, AI 데이터베이스 문서 참조 응답, 스트리밍 지원.
+     */
+    readonly ai: AIAPI;
     /**
      * Queue API (메시지 큐)
      * NATS JetStream 기반 고신뢰 메시지 큐. 발행, 소비, Ack, Nack 지원.
      */
     readonly queue: QueueAPI;
+    /**
+     * Analytics API (웹 분석)
+     * 페이지뷰, 커스텀 이벤트, 세션 추적. GA4 수준의 웹 분석 제공.
+     */
+    readonly analytics: AnalyticsAPI;
+    /**
+     * Endpoint API (로컬 모델 터널 dumb pipe)
+     * 사용자 PC GPU 모델 (ComfyUI / A1111 / Hunyuan3D / 자체 FastAPI 등) 을 `cb_pk_*`
+     * 한 키로 호출. 라벨로 라우팅, 페이로드/응답은 그대로 통과.
+     */
+    readonly endpoint: EndpointAPI;
+    /**
+     * Support API (사용자 제보 / 이슈 큐)
+     * 앱 사용자가 운영자에게 버그/질문/요청을 발행. AI 가 자동 분류/우선순위 처리.
+     */
+    readonly support: SupportAPI;
     constructor(config?: ConnectBaseConfig);
+    /**
+     * 현재 페이지가 OAuth 리다이렉트 콜백 페이지인지 판별.
+     *
+     * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
+     * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
+     * 패턴이면 true. 콜백 페이지에서 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     */
+    private isOAuthCallbackUrl;
+    /**
+     * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
+     *
+     * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
+     * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
+     *
+     * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
+     */
+    restoreSession(): Promise<boolean>;
     /**
      * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)
      */
@@ -5766,4 +8674,4 @@ declare class ConnectBase {
     updateConfig(config: Partial<ConnectBaseConfig>): void;
 }
 
-export { type AckMessagesRequest, type AdReportResponse, type AdReportSummary, AdsAPI, type AggregateResult, type AggregateStage, ApiError, type ApiKeyItem, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchSetPageMetaRequest, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ChatRequest, type ChatResponse, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreateRelationRequest, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabasePresenceState, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchApiKeysResponse, type FetchDataResponse, type FetchFilesResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConnectionState, type GameConnectionStatus, type GameDelta, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchmakingTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type Playlist, type PlaylistItem, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type StateChange, type StateChangeHandler, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamMessage, type StreamOptions, type StreamSession, type StreamTokenCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableIndex, type TableRelation, type TableSchema, type TransactionRead, type TransactionWrite, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateApiKeyRequest, type UpdateApiKeyResponse, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateLobbyRequest, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoVisibility, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported };
+export { AIAPI, type AIChatRequest, type AIChatResponse, type AIMessage, type AISource, type AIStreamChunk, type AITool, type AIToolCall, type AIToolEvent, AUTH_MEMBER_ID_TOKEN, type AckMessagesRequest, type AdMobDailyReport, type AdMobReportResponse, type AdMobReportSummary, type AdReportResponse, type AdReportSummary, type AdmobConnectionInfo, AdsAPI, type AdsenseConnectionInfo, type AgenticSearchProgress, type AggregateResult, type AggregateStage, type AnalyticsConfig, type AnalyticsEvent, ApiError, type ApiErrorDetail, type AppStatsResponse, type ArchivePolicy, type AtomicOperator, type AtomicOperatorType, AuthError, type AuthSettingsResponse, type BackupInfo, type BatchOperation, type BatchOperationResult, type BatchSetPageMetaRequest, type BatchWriteResult, type BillingCycle, type BillingKeyResponse, type BiometricInfo, type BiometricResult, type BulkCreateResponse, type BulkError, type CPUInfo, type CancelPaymentRequest, type CancelPaymentResponse, type CancelSubscriptionRequest, type CategoryInfo, type Channel, type ChannelMembership, type ChargeWithBillingKeyRequest, type ChargeWithBillingKeyResponse, type ChatMessage, type ClientMessage, type ColumnSchema, type CommentListResponse, type CompleteUploadRequest, type CompleteUploadResponse, type ConfirmBillingKeyRequest, type ConfirmPaymentRequest, type ConfirmPaymentResponse, ConnectBase, type ConnectBaseConfig, type ConnectedData, type ConnectionState, type ConsentOptions, type ConsumeMessagesResponse, type ConsumeOptions, type CopyTableRequest, type CopyTableResponse, type CreateBackupRequest, type CreateChannelRequest, type CreateCheckoutSessionRequest, type CreateCheckoutSessionResponse, type CreateColumnRequest, type CreateDataRequest, type CreateDocumentRequest, type CreateFolderRequest, type CreateFolderResponse, type CreateGeoIndexRequest, type CreateIndexRequest, type CreateLobbyRequest, type CreatePlaylistRequest, type CreatePublicKeyRequest, type CreatePublicKeyResponse, type CreateRelationRequest, type CreateRoomResult, type CreateSearchIndexRequest, type CreateSecurityRuleRequest, type CreateSubscriptionRequest, type CreateTableRequest, type CreateTriggerRequest, type CreateVideoStorageRequest, type DailyReport, type DataItem, type DataType, type DatabaseChange, type DatabaseChangeMessage, type DatabaseChangeType, type DatabaseRealtimeConnectOptions, type DatabaseRealtimeFilter, type DatabaseRealtimeHandlers, type DatabaseRealtimeSubscription, type DatabaseSnapshot, type DatabaseSnapshotMessage, type DatabaseSubscribeOptions, type DeleteWhereResponse, type DeviceInfo, type DocumentResponse, type EnabledProviderInfo, type EnabledProvidersResponse, EndpointAPI, type EndpointCallInit, type ErrorHandler, type ErrorMessage, type ErrorReport, type ErrorTrackerConfig, type ErrorType, type ExportDataRequest, type ExportDataResponse, type FetchDataResponse, type FetchFilesResponse, type FetchPublicKeysResponse, type FileItem, type FileStats, GameAPI, type GameAction, type GameClientConfig, type GameConfig, GameConfigAPI, type GameConfigPatch, type GameConnectionState, type GameConnectionStatus, type GameDelta, GameError, type GameErrorCode, type GameEventHandlers, type GamePlayer, GameRoom, type GameRoomConfig, type GameRoomInfo, GameRoomTransport, type GameServerMessage, type GameServerMessageType, type GameState, type GameTransportConfig, type GenerateUploadURLByPathRequest, type GenerateUploadURLRequest, type GenerateUploadURLResponse, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GeoWithin, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, type GuestMemberSignInResponse, type HistoryResponse, type ICEServer, type ICEServersResponse, type ImageResult, type ImportDataRequest, type ImportDataResponse, type IndexAnalysis, type IndexRecommendation, type InitUploadResponse, type InvokeFunctionRequest, type InvokeFunctionResponse, type IssueBillingKeyRequest, type IssueBillingKeyResponse, type JoinQueueRequest, type JoinRoomRequest, type JoinRoomResponse, type KnowledgeSearchRequest, type KnowledgeSearchResponse, type KnowledgeSearchResult, type LeaderboardEntry, type LeaderboardListResponse, type LeaderboardScoreEntry, type LifecyclePolicy, type ListBillingKeysResponse, type ListDocumentsResponse, type ListPageMetasOptions, type ListPageMetasResponse, type ListSubscriptionPaymentsRequest, type ListSubscriptionPaymentsResponse, type ListSubscriptionsRequest, type ListSubscriptionsResponse, type LobbyInfo, type LobbyInvite, type LobbyMember, type LobbyVisibility, type MatchResult, type MatchmakingTicket, type MatchqueueListResponse, type MatchqueueTicket, type MemberInfoResponse, type MemberSignInRequest, type MemberSignInResponse, type MemberSignUpRequest, type MemberSignUpResponse, type MembershipTier, type MemoryInfo, type MessageHandler, type MigrateDataRequest, type MigrateDataResponse, type MoveFileRequest, type NackMessageRequest, NativeAPI, type OAuthCallbackResponse, type OAuthProvider, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentProvider, type PaymentStatus, type PeerInfo, type Platform, type PlayerEvent, type PlayerStats, type Playlist, type PlaylistItem, type PollUntilOptions, type PongMessage, type PopulateOption, type Position, type PreparePaymentRequest, type PreparePaymentResponse, type PresenceChangeHandler, type PresenceInfo, type PresenceSetOptions, type PresenceStatus, type PresenceStatusResult, type PublicKeyItem, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type QualityProgress, type QueryOptions, type QueueInfoResponse, type QueueMessage, type ReadReceiptHandler, type ReadReceiptInfo, type RealtimeConnectOptions, type RealtimeMessage, type RegisterDeviceRequest, type RelationType, type RenameFileRequest, type RenameFileResponse, type ReplayHighlight, type ReplayInfo, type ReplayPlayerInfo, type RestoreBackupRequest, type RestoreBackupResponse, type RetentionPolicy, type RoomInfo, type RoomStaleMessage, type RoomStats, type RoomsResponse, type SaveDialogOptions, type SaveDialogResult, type ScriptDetailResponse, type ScriptListResponse, type ScriptMeta, type ScriptVersion, type ScriptVersionListResponse, type SearchIndex, type SearchOptions, type SearchResponse, type SearchResult, type SecurityRule, type SendOptions, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StreamContentPart, type StreamDoneCallback, type StreamDoneData, type StreamErrorCallback, type StreamHandlers, type StreamImageURLPart, type StreamMessage, type StreamOptions, type StreamSession, type StreamTextPart, type StreamTokenCallback, type StreamToolCallCallback, type StreamToolResultCallback, type StreamURLResponse, type SubscribeOptions, type SubscribeTopicRequest, type SubscribedData, type Subscription, type SubscriptionPaymentResponse, type SubscriptionPaymentStatus, type SubscriptionResponse, type SubscriptionStatus, type SuperChat, type SystemInfo, type TTLConfig, type TableAccessLevel, type TableColumnDef, type TableIndex, type TableRelation, type TableSchema, type TableSchemaDefinition, type TokenPersistence, type TransactionRead, type TransactionResult, type TransactionWrite, type TransactionWriteResult, type TranscodeStatus, type TransportType, type Trigger, type TriggerEvent, type TriggerHandlerType, type TypingChangeHandler, type TypingInfo, type UpdateBillingKeyRequest, type UpdateChannelRequest, type UpdateColumnRequest, type UpdateCustomDataRequest, type UpdateCustomDataResponse, type UpdateDataRequest, type UpdateDocumentRequest, type UpdateLobbyRequest, type UpdatePublicKeyRequest, type UpdatePublicKeyResponse, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoListOptions, type VideoListResponse, VideoProcessingError, type VideoQuality, type VideoStatus, type VideoStorage, type VideoStorageListResponse, type VideoVisibility, type VoiceChannel, type VoiceMember, type WaitOptions, type WatchHistoryItem, type WebPushSubscription, type WebRTCConnectOptions, type WebRTCConnectionState, type WebRTCMode, type WhereCondition, type WhereOperator, ConnectBase as default, detectInAppBrowser, escapeToExternalBrowser, isWebTransportSupported, toCreateRoomWire };