interface ApiErrorDetail {
    code: string;
    message: string;
    details?: unknown;
}
declare class ApiError extends Error {
    statusCode: number;
    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 / 인증 토큰 미저장
 *   - 쿼리스트링은 키 단위 redact 가 아니라 통째로 제거 (토큰/PII 누출 가능성 0)
 *   - 따라서 `/v1/auth/*`, `/v1/oauth/token` 등 민감 endpoint 도 path 만 보존
 */
interface RecentApiCall {
    method: string;
    path: string;
    status: number;
    duration_ms: number;
    timestamp: string;
}

type TokenPersistence = "localStorage" | "sessionStorage" | "none";
interface HttpClientConfig {
    baseUrl: string;
    /**
     * Public Key (cb_pk_* 형식). 콘솔 → 설정 → API 에서 발급.
     * 브라우저/클라이언트에서 사용 (Row Level Security 적용).
     */
    publicKey?: string;
    /**
     * Secret Key (cb_sk_* 형식). 사용자 프로필에서 발급.
     * 서버 환경에서만 사용 (전체 권한, 절대 노출 금지).
     */
    secretKey?: string;
    /**
     * 이 클라이언트가 속한 앱 ID (선택). 설정 시, refresh 응답이 **다른 앱**의 access token 을
     * 돌려주면(예: 같은 브라우저의 다른 앱 세션 쿠키로 복구된 토큰) 해당 토큰을 채택하지 않고
     * 세션 없음으로 처리한다. 백엔드 re-issue 가 app-scoped 가드로 1차 차단하지만, SDK 측에서도
     * 방어적으로 한 번 더 막는다 (platform-issue 019e86d1). appId 미설정 시 이 가드는 비활성.
     */
    appId?: 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 extends AbortOptions {
    skipAuth?: boolean;
    headers?: Record<string, string>;
}
declare class HttpClient {
    private config;
    private isRefreshing;
    private refreshPromise;
    private storageKey;
    private refreshFailureCount;
    private refreshLockedUntil;
    /**
     * 최근 API 호출 breadcrumb (PII strip 후 저장). platform_issue 발행 시 자동 첨부 가능.
     * `client.support.getRecentApiCalls()` 로 외부 노출.
     */
    private recentCalls;
    /**
     * 부팅 시 fire-and-forget 으로 시작한 cookie 기반 복구 promise. `prepareHeaders` 가
     * 인증 호출을 보내기 직전에 이 promise 를 await 해, 페이지 진입 직후 첫 API 호출이
     * 메모리 토큰 빈 상태로 401 받는 race 를 막는다 (platform-issue 019e638d, 2026-05-26).
     * 한 번 settle 되면 그 결과(메모리 적재 또는 미로그인)가 항상 반영되어 있다.
     */
    private bootRestorePromise;
    private bootRestoreAlwaysAwait;
    constructor(config: HttpClientConfig);
    /**
     * 페이지 진입 시 fire-and-forget 으로 시작된 cookie 복구 promise 를 SDK 가 등록한다.
     * 같은 promise 가 `prepareHeaders` 에서 await 되어, 첫 인증 호출이 cookie 복구
     * 완료 후 발화한다.
     *
     * options.alwaysAwait=true 면 세션 힌트가 없어도 첫 인증 호출이 이 promise 를
     * 기다린다 — OAuth 리다이렉트 콜백처럼 "이 부트 promise 가 곧 세션을 만든다"는 것이
     * 확실한 흐름용 (일반 cookie 복구는 힌트 기반 fast-path 적용).
     */
    setBootRestorePromise(p: Promise<boolean>, options?: {
        alwaysAwait?: 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;
    private buildSessionHintKey;
    private markSessionHint;
    private clearSessionHint;
    private hasSessionHint;
    /**
     * 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 가 설정되어 있는지 확인
     */
    hasPublicKey(): boolean;
    /**
     * Public Key 반환
     */
    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;
    /**
     * 이 클라이언트에 설정된 앱 ID 반환 (미설정 시 undefined).
     *
     * 콘솔(앱 소유자 JWT) 경로를 호출하기 전에 appId 유무를 확인하기 위한 public 접근자.
     * private `config` 필드를 access-modifier 관통 cast 없이 노출한다.
     */
    getAppId(): string | undefined;
    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 AdsenseConnectionInfo {
    is_connected: boolean;
    email?: string;
    account_id?: string;
}
interface AdmobConnectionInfo {
    is_connected: boolean;
    email?: string;
    account_id?: string;
    publisher_id?: string;
}
interface GoogleConnectionStatus {
    adsense: AdsenseConnectionInfo;
    admob: AdmobConnectionInfo;
}
interface AdReportSummary {
    total_earnings: number;
    total_impressions: number;
    total_clicks: number;
    ctr: number;
    cpc: number;
    rpm: number;
}
interface DailyReport {
    date: string;
    earnings: number;
    impressions: number;
    clicks: number;
    ctr: number;
}
interface AdReportResponse {
    summary: AdReportSummary;
    daily: DailyReport[];
}
interface AdMobReportSummary {
    total_earnings: number;
    total_impressions: number;
    total_clicks: number;
    total_ad_requests: number;
    total_matched_requests: number;
    impression_ctr: number;
    impression_rpm: number;
    match_rate: number;
}
interface AdMobDailyReport {
    date: string;
    earnings: number;
    impressions: number;
    clicks: number;
    ad_requests: number;
    matched_requests: number;
    impression_ctr: number;
}
interface AdMobReportResponse {
    summary: AdMobReportSummary;
    daily: AdMobDailyReport[];
}
declare class AdsAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * AdSense / AdMob 연결 상태 확인 (중첩 구조)
     *
     * @returns `{ adsense, admob }` 각각 연결 상태·이메일·계정 ID
     *
     * @example
     * ```typescript
     * const status = await cb.ads.getConnectionStatus()
     * 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)
     * }
     * ```
     */
    getConnectionStatus(): Promise<GoogleConnectionStatus>;
    /**
     * AdSense 리포트 조회 (일별 데이터 + 요약)
     *
     * @param startDate - 시작일 (YYYY-MM-DD), 미지정 시 최근 30일
     * @param endDate - 종료일 (YYYY-MM-DD), 미지정 시 최근 30일
     * @returns 요약 + 일별 데이터
     *
     * @example
     * ```typescript
     * const report = await cb.ads.getReport('2025-01-01', '2025-01-31')
     * console.log('총 수익:', report.summary.total_earnings)
     * report.daily.forEach(day => {
     *     console.log(`${day.date}: $${day.earnings}`)
     * })
     * ```
     */
    getReport(startDate?: string, endDate?: string): Promise<AdReportResponse>;
    /**
     * 최근 30일 AdSense 요약 조회
     *
     * @returns 30일 합산 수익, 노출, 클릭, CTR, CPC, RPM
     *
     * @example
     * ```typescript
     * const summary = await cb.ads.getReportSummary()
     * console.log(`총 수익: $${summary.total_earnings}`)
     * console.log(`RPM: $${summary.rpm}`)
     * ```
     */
    getReportSummary(): Promise<AdReportSummary>;
    /**
     * AdMob 리포트 조회 (일별 데이터 + 요약)
     *
     * @param startDate - 시작일 (YYYY-MM-DD), 미지정 시 최근 30일
     * @param endDate - 종료일 (YYYY-MM-DD), 미지정 시 최근 30일
     * @returns 요약 + 일별 데이터
     *
     * @example
     * ```typescript
     * const report = await cb.ads.getAdMobReport('2025-01-01', '2025-01-31')
     * console.log('총 수익:', report.summary.total_earnings)
     * console.log('매치율:', report.summary.match_rate + '%')
     * ```
     */
    getAdMobReport(startDate?: string, endDate?: string): Promise<AdMobReportResponse>;
    /**
     * 최근 30일 AdMob 요약 조회
     *
     * @returns 30일 합산 수익, 노출, 클릭, 광고 요청, 매치율, RPM
     *
     * @example
     * ```typescript
     * const summary = await cb.ads.getAdMobReportSummary()
     * console.log(`총 수익: $${summary.total_earnings}`)
     * console.log(`매치율: ${summary.match_rate}%`)
     * ```
     */
    getAdMobReportSummary(): Promise<AdMobReportSummary>;
}

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;
    /**
     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
     */
    hybrid?: boolean;
    toolGroupId?: string;
    /**
     * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에
     * **재투입하기 전** N 자(rune 기준)로 잘라낸다(말미에 잘림 표시). SSE `onToolEvent` 의
     * `tool_end.result` 로 표시되는 값은 원문을 유지한다.
     *
     * 거대한 도구 결과(예: 복잡한 페이지의 `browser_snapshot`)가 누적 컨텍스트를 부풀려
     * 매 턴 prefill 을 무겁게 만들 때, 표시는 원문으로 두고 모델 재투입분만 압축해
     * 지연을 줄이는 용도. 미지정/0 이면 자르지 않는다.
     */
    toolResultMaxChars?: number;
    /**
     * 요청에 포함한 MCP 도구(`tools`)를 호출할 외부 MCP 서버의 Public Key (cb_pk_* 형식).
     * MCP 도구를 직접 넘기지 않으면 불필요하다.
     */
    mcpPublicKey?: string;
}
/**
 * `chatStream` 콜백.
 *
 * 대부분 콜백은 SSE 이벤트 종류별로 매핑되며, `onAbort` 는 호출자가 전달한
 * `AbortSignal` 로 스트림을 취소했을 때 호출된다(에러가 아니므로 `onError` 와 구분).
 */
interface AIChatStreamCallbacks {
    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;
    /**
     * `options.signal` 로 스트림을 취소(abort)했을 때 호출된다. 정상적인
     * 사용자 취소이므로 `onError` 대신 본 콜백이 호출되며, `onDone` 은 호출되지
     * 않는다. 미지정 시 abort 는 조용히(예외 없이) 종료된다.
     */
    onAbort?: () => void;
}
/**
 * `chatStream` 호출 옵션. `signal` 로 진행 중인 SSE 스트림을 취소할 수 있다.
 */
interface AIChatStreamOptions {
    /**
     * 진행 중인 스트림을 취소하기 위한 `AbortSignal`. abort 하면 SSE 연결이
     * 닫히고, 서버는 요청 컨텍스트 취소를 통해 server-side agent tool loop
     * (`toolGroupId` 사용 시)까지 중단한다.
     */
    signal?: AbortSignal;
}
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;
    error?: string;
    message?: string;
}

/**
 * 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
 * })
 * ```
 */
/**
 * # 🔒 보안 — LLM API key 는 절대 클라이언트에 hardcode 금지
 *
 * 본 SDK 의 `chat` / `chatStream` 은 **ConnectBase 서버 프록시 경유** — provider (OpenAI/Claude/
 * Gemini/Ollama/vLLM/...) API key 는 `AppAIConfig` 에 암호화 저장된 상태로 ConnectBase 가 server-side
 * 에서만 복호화하여 사용합니다. 클라이언트는 user public key (또는 secret key) 만 알면 됩니다.
 *
 * **❌ 안티 패턴 — 즉시 다른 운영자에게 cross_app_issue 로 알려지고 차단됨**:
 * ```ts
 * // 브라우저 정적 자산에 raw provider URL + key — 절대 금지
 * fetch("https://api.openai.com/v1/chat/completions", {
 *     headers: { Authorization: "Bearer sk-..." }
 * })
 * // 또는
 * fetch("https://tunnel.connectbase.world/<id>/v1/chat/completions", {
 *     headers: { Authorization: "Bearer <vLLM key>" }
 * })
 * ```
 * DevTools → Network 한 번이면 누구나 key 추출 → 추론 비용 폭주 / GPU 자원 고갈.
 *
 * **✅ 베스트프랙티스 — 본 SDK 호출만 사용**:
 * ```ts
 * await cb.ai.chatStream({ messages: [...], provider: "openai_compatible" }, callbacks)
 * ```
 */
declare class AIAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * AI 채팅 (동기). ConnectBase 서버 프록시 경유 — provider API key 는 server-side `AppAIConfig`
     * 에서만 사용되어 클라이언트에 노출되지 않습니다. raw provider URL 직접 호출 금지 (안티 패턴).
     */
    chat(request: AIChatRequest): Promise<AIChatResponse>;
    /**
     * AI 채팅 스트리밍 (SSE)
     *
     * @param request AI 채팅 요청
     * @param callbacks 스트림 이벤트 콜백 (토큰/추론/도구/검색/완료/에러/취소)
     * @param options 선택적 옵션. `options.signal` 에 `AbortSignal` 을 전달하면
     *   호출자가 진행 중인 스트림을 취소할 수 있다. abort 시 SSE 연결이 닫히고,
     *   서버는 요청 컨텍스트(`c.Request.Context()`) 취소를 통해 server-side agent
     *   tool loop (`toolGroupId` 사용 시)까지 함께 중단한다. abort 는 정상적인
     *   사용자 취소이므로 `onError` 가 아니라 `callbacks.onAbort?.()` 가 호출되며
     *   (지정 시), `onDone` 은 호출되지 않는다.
     *
     * @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)
     * })
     * ```
     *
     * @example 취소(stop 버튼)
     * ```typescript
     * const controller = new AbortController()
     * // stop 버튼: controller.abort()
     * await cb.ai.chatStream(
     *     { messages: [{ role: 'user', content: '...' }], toolGroupId: 'tg-id' },
     *     { onToken: (c) => process.stdout.write(c), onAbort: () => console.log('취소됨') },
     *     { signal: controller.signal },
     * )
     * ```
     */
    chatStream(request: AIChatRequest, callbacks: AIChatStreamCallbacks, options?: AIChatStreamOptions): Promise<void>;
}

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.trackEvent('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;
}

/** 앱 멤버 회원가입 요청 */
interface MemberSignUpRequest {
    login_id: string;
    password: string;
    nickname?: string;
}
/** 앱 멤버 회원가입 응답 */
interface MemberSignUpResponse {
    member_id: string;
    nickname: string;
    access_token: string;
    refresh_token: string;
}
/** 앱 멤버 로그인 요청 */
interface MemberSignInRequest {
    login_id: string;
    password: string;
}
/** 앱 멤버 로그인 응답 */
interface MemberSignInResponse {
    member_id: string;
    nickname: string;
    access_token: string;
    refresh_token: string;
}
/** 앱 멤버 내 정보 응답 */
interface MemberInfoResponse {
    member_id: string;
    nickname: string;
    is_active: boolean;
    custom_data: Record<string, unknown>;
    /** 멤버 이메일 (EMAIL identity 에서 추출, 없으면 빈 문자열) */
    email?: string;
    /** 멤버 역할 — RLS 규칙에서 `auth.role` 로 참조 (예: "admin", "moderator") */
    role?: string;
    /**
     * 현재 세션이 게스트(identity 가 전혀 없는 멤버 또는 레거시 GUEST identity)인지 여부.
     * 신규 게스트 로그인은 제거됐으나, 기존 게스트 멤버 식별을 위해 유지된다.
     */
    is_guest?: boolean;
    /**
     * 현재 세션의 인증 방식 식별자.
     *   "guest" | "email" | "username" | "oauth_google" | "oauth_kakao" |
     *   "oauth_naver" | "oauth_apple" | "oauth_github" | "oauth_discord"
     * OAuth 외 미래 provider 가 추가되면 동일한 `oauth_<provider>` 컨벤션을 따른다.
     * identity 가 전혀 없는 경우 빈 문자열.
     */
    auth_provider?: string;
}
/** 앱 멤버 custom_data 수정 요청 */
interface UpdateCustomDataRequest {
    custom_data: Record<string, unknown>;
}
/** 앱 멤버 custom_data 수정 응답 */
interface UpdateCustomDataResponse {
    member_id: string;
    custom_data: Record<string, unknown>;
}
/** 앱 인증 설정 응답 */
interface AuthSettingsResponse {
    /** 아이디/비밀번호 로그인 허용 여부 */
    allow_id_password_login: boolean;
    /** 활성화된 OAuth 프로바이더 목록 (GOOGLE, KAKAO, NAVER, APPLE, GITHUB, DISCORD) */
    enabled_oauth_providers: string[];
}

declare class AuthAPI {
    private http;
    private analytics;
    constructor(http: HttpClient);
    /**
     * AnalyticsAPI 주입 — 로그인/가입/로그아웃 시 방문자 트래커에 member_id 를 전달하여
     * 게스트 방문자를 회원과 연결한다. ConnectBase 컨스트럭터에서 내부적으로 호출된다.
     */
    _attachAnalytics(analytics: AnalyticsAPI): void;
    private notifyVisitorTracker;
    /**
     * 앱의 인증 설정 조회
     * 어떤 로그인 방식이 허용되는지 확인합니다.
     *
     * @example
     * ```typescript
     * const settings = await client.auth.getAuthSettings()
     * if (settings.allow_id_password_login) {
     *     // 로그인 폼 표시
     * } else if (settings.enabled_oauth_providers.includes('GOOGLE')) {
     *     // 구글 소셜 로그인 버튼 표시
     * }
     * ```
     */
    getAuthSettings(): Promise<AuthSettingsResponse>;
    /**
     * 앱 멤버 회원가입 (아이디/비밀번호 기반)
     * 앱에 새로운 멤버를 등록합니다.
     *
     * @example
     * ```typescript
     * const result = await client.auth.signUpMember({
     *     login_id: 'myuser123',
     *     password: 'password123',
     *     nickname: 'John'
     * })
     * console.log('가입 완료:', result.member_id)
     * ```
     */
    signUpMember(data: MemberSignUpRequest): Promise<MemberSignUpResponse>;
    /**
     * 앱 멤버 로그인 (아이디/비밀번호 기반)
     * 기존 멤버로 로그인합니다.
     *
     * @example
     * ```typescript
     * const result = await client.auth.signInMember({
     *     login_id: 'myuser123',
     *     password: 'password123'
     * })
     * console.log('로그인 성공:', result.member_id)
     * ```
     */
    signInMember(data: MemberSignInRequest): Promise<MemberSignInResponse>;
    /**
     * 현재 로그인한 멤버 정보 조회
     * custom_data를 포함한 멤버 정보를 반환합니다.
     *
     * @example
     * ```typescript
     * const me = await client.auth.getMe()
     * console.log('내 정보:', me.nickname, me.custom_data)
     * ```
     */
    getMe(): Promise<MemberInfoResponse>;
    /**
     * 현재 로그인한 멤버의 custom_data 수정
     * PATCH 방식으로 기존 데이터에 머지됩니다. 값을 null로 설정하면 해당 키가 삭제됩니다.
     *
     * @example
     * ```typescript
     * // 키 추가/수정
     * await client.auth.updateCustomData({
     *     custom_data: { role: 'admin', level: 5 }
     * })
     *
     * // 키 삭제 (null 전달)
     * await client.auth.updateCustomData({
     *     custom_data: { role: null }
     * })
     * ```
     */
    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;
    }>;
    /**
     * 로그아웃
     */
    signOut(): Promise<void>;
}

/**
 * 서버(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?: 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;
    /** 필수 필드 여부 (기본 `false`) */
    is_required?: boolean;
    /** 기본값 (서버는 임의 타입을 허용하므로 `unknown`) */
    default_value?: unknown;
    description?: string;
    /**
     * 필드 레벨 암호화 활성화 여부.
     * true로 설정 시 AES-256-GCM으로 DB에 암호화 저장되며, 조회 시 자동 복호화됩니다.
     * 암호화된 필드는 DB 레벨 필터/정렬이 불가하며, 앱 레벨 검색은 정상 동작합니다.
     * 서버에 SECRET_ENCRYPTION_KEY가 설정되어 있어야 합니다.
     */
    encrypted?: boolean;
    /**
     * @deprecated 서버가 무시합니다. 컬럼 순서는 서버가 자동 관리합니다.
     */
    order?: number;
    /**
     * @deprecated 서버가 해당 필드를 저장하지 않습니다.
     */
    validation_rule?: string;
}
interface UpdateColumnRequest {
    data_type?: DataType;
    is_required?: boolean;
    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;
    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;
}
/**
 * 컬럼 정의. 서버는 두 가지 형식 중 하나로 저장합니다:
 * - 플랫: 타입 문자열만 (`'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 {
    id: string;
    data: Record<string, unknown>;
    created_at: string;
    updated_at: string;
}
interface CreateDataRequest {
    data: Record<string, unknown>;
}
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 {
    /** 조회된 문서 배열 */
    data: DataItem[];
    /**
     * 총 매칭 문서 수.
     *
     * `count: false` 로 조회한 경우: 마지막 페이지(반환 건수 < limit)면 서버가 정확한
     * 총계를 파생해 돌려주고, 아니면 `-1` (미상) 이 반환됩니다.
     * `cursor` 를 사용한 조회는 기본적으로 `-1` (잔여 카운트가 필요하면 `count: true` 명시).
     */
    total_count: number;
    /**
     * 다음 페이지 커서 (keyset 페이지네이션).
     *
     * 값이 있으면 다음 페이지가 있을 수 있으며, 다음 요청의 `cursor` 옵션에 그대로
     * 전달하면 됩니다. 없으면 마지막 페이지입니다. 사용자 정렬(orderBy)과 함께는
     * 제공되지 않습니다.
     */
    next_cursor?: string;
}
interface QueryOptions {
    limit?: number;
    offset?: number;
    orderBy?: string;
    orderDirection?: "asc" | "desc";
    where?: WhereCondition;
    /** 반환할 필드 목록 (Projection) - 지정된 필드만 반환 */
    select?: string[];
    /** 제외할 필드 목록 - 지정된 필드를 제외하고 반환 */
    exclude?: string[];
    /**
     * `false` 면 `total_count` 계산(서버측 COUNT 쿼리)을 생략합니다.
     *
     * 필터가 붙은 COUNT 는 본 조회와 같은 비용의 스캔을 한 번 더 도는 것이므로,
     * 총계가 필요 없는 목록/무한스크롤 조회는 `count: false` 로 눈에 띄게 빨라집니다.
     * 생략 시 기본값은 `true` (기존 동작 유지). `cursor` 사용 시 기본값은 `false`.
     */
    count?: boolean;
    /**
     * Keyset 페이지네이션 커서 — 이전 응답의 `next_cursor` 값.
     *
     * 설정하면 `offset` 은 무시되고 생성순(id) 정렬로 커서 이후 문서를 반환합니다.
     * `offset` 방식은 깊은 페이지일수록 느려지지만 커서 방식은 페이지 깊이와 무관하게
     * 일정합니다 (무한스크롤 권장). `orderBy` 와 함께 쓸 수 없습니다.
     */
    cursor?: string;
}
type WhereCondition = {
    /** OR 조건: 배열 내 조건들 중 하나 이상 만족 */
    $or?: WhereCondition[];
} & Record<string, unknown | WhereOperator>;
interface WhereOperator {
    $eq?: unknown;
    $ne?: unknown;
    $gt?: number;
    $gte?: number;
    $lt?: number;
    $lte?: number;
    $in?: unknown[];
    $nin?: unknown[];
    $contains?: string;
    $startsWith?: string;
    $endsWith?: string;
    /** 정규식 매칭 (MySQL REGEXP) */
    $matches?: string;
    /** 범위 쿼리 [min, max] */
    $between?: [number, number];
    /** NULL 체크 (true: null인 문서, false: null이 아닌 문서) */
    $isNull?: boolean;
    /** JSON 배열에 특정 값이 포함되어 있는지 확인 */
    $arrayContains?: unknown;
    /** JSON 배열에 주어진 값들 중 하나라도 포함되어 있는지 확인 */
    $arrayContainsAny?: unknown[];
}
interface BulkCreateResponse {
    created: DataItem[];
    failed?: BulkError[];
    total: number;
    success: number;
}
interface BulkError {
    index: number;
    error: string;
}
interface DeleteWhereResponse {
    deleted_count: number;
    failed_count?: number;
}
interface SecurityRule {
    id: string;
    app_id: string;
    table_name: string;
    rules: Record<string, unknown>;
    is_active: boolean;
    priority: number;
    created_at: string;
    updated_at: string;
}
interface CreateSecurityRuleRequest {
    table_name: string;
    rules: Record<string, unknown>;
    is_active?: boolean;
    priority?: number;
}
interface UpdateSecurityRuleRequest {
    rules?: Record<string, unknown>;
    is_active?: boolean;
    priority?: number;
}
interface TableIndex {
    id: string;
    name: string;
    fields: string[];
    unique: boolean;
    sparse: boolean;
    created_at: string;
}
interface CreateIndexRequest {
    name: string;
    fields: string[];
    unique?: boolean;
    sparse?: boolean;
}
interface IndexAnalysis {
    recommendations: IndexRecommendation[];
    slow_queries: SlowQueryInfo[];
    existing_indexes: TableIndex[];
    summary: {
        total_queries: number;
        slow_query_count: number;
        avg_response_time: number;
        index_utilization: number;
        recommended_count: number;
    };
}
interface IndexRecommendation {
    fields: string[];
    reason: string;
    estimated_improvement: string;
    priority: string;
    query_count: number;
    avg_query_time: number;
}
interface SlowQueryInfo {
    pattern: string;
    count: number;
    avg_time: number;
}
type RelationType = "one-to-one" | "one-to-many" | "many-to-one" | "many-to-many";
interface TableRelation {
    id: string;
    app_id: string;
    source_table: string;
    source_field: string;
    target_table: string;
    target_field: string;
    relation_type: RelationType;
    alias: string;
    cascade_delete: boolean;
    created_at: string;
    updated_at: string;
}
interface CreateRelationRequest {
    source_table: string;
    source_field: string;
    target_table: string;
    target_field?: string;
    relation_type: RelationType;
    alias?: string;
    cascade_delete?: boolean;
}
interface PopulateOption {
    field: string;
    from?: string;
    as?: string;
    select?: string[];
    limit?: number;
    orderBy?: string;
    order?: "asc" | "desc";
    populate?: PopulateOption[];
}
type TriggerEvent = "create" | "update" | "delete" | "all";
type TriggerHandlerType = "function" | "workflow" | "webhook" | "inline";
interface Trigger {
    id: string;
    app_id: string;
    name: string;
    table_name: string;
    event: TriggerEvent;
    condition?: Record<string, unknown>;
    handler_type: TriggerHandlerType;
    handler_id?: string;
    handler_url?: string;
    handler_action?: Record<string, unknown>;
    is_active: boolean;
    order: number;
    created_at: string;
    updated_at: string;
}
interface CreateTriggerRequest {
    name: string;
    table_name: string;
    event: TriggerEvent;
    handler_type: TriggerHandlerType;
    handler_id?: string;
    handler_url?: string;
    handler_action?: Record<string, unknown>;
    condition?: Record<string, unknown>;
    is_active?: boolean;
    order?: number;
}
interface UpdateTriggerRequest {
    name?: string;
    event?: TriggerEvent;
    handler_type?: TriggerHandlerType;
    handler_id?: string;
    handler_url?: string;
    handler_action?: Record<string, unknown>;
    condition?: Record<string, unknown>;
    is_active?: boolean;
    order?: number;
}
interface AggregateStage {
    $match?: Record<string, unknown>;
    $group?: {
        _id: string | Record<string, unknown>;
        [key: string]: unknown;
    };
    $sort?: Record<string, 1 | -1>;
    $limit?: number;
    $skip?: number;
    $project?: Record<string, unknown>;
    $unwind?: string;
    $count?: string;
    $lookup?: {
        from: string;
        localField: string;
        foreignField: string;
        as: string;
    };
    $bucket?: {
        groupBy: string;
        boundaries: unknown[];
        default?: unknown;
        output?: Record<string, unknown>;
    };
    $bucketAuto?: {
        groupBy: string;
        buckets: number;
        output?: Record<string, unknown>;
        granularity?: string;
    };
    $addFields?: Record<string, unknown>;
}
interface AggregateResult {
    results: Record<string, unknown>[];
    count: number;
}
interface SearchOptions {
    case_sensitive?: boolean;
    whole_word?: boolean;
    fuzzy?: boolean;
    fuzzy_distance?: number;
    highlight?: boolean;
    limit?: number;
    offset?: number;
    min_score?: number;
}
interface SearchResult {
    id: string;
    data: Record<string, unknown>;
    score: number;
    highlights?: Record<string, string>;
}
interface SearchResponse {
    results: SearchResult[];
    total_count: number;
    query: string;
}
/**
 * 지리 좌표. 서버는 `{ lat, lng }`, `{ latitude, longitude }`, `[lng, lat]` 세 형식을 모두 받지만
 * SDK 는 `{ lat, lng }` 를 표준으로 사용한다.
 */
interface GeoPoint {
    lat: number;
    lng: number;
}
interface GeoNear {
    center: GeoPoint;
    /** 최대 거리 (미터) */
    max_distance: number;
    /** 최소 거리 (미터, 도넛 검색) */
    min_distance?: number;
}
interface GeoBoundingBox {
    bottom_left: GeoPoint;
    top_right: GeoPoint;
}
interface GeoPolygon {
    /** 폴리곤 꼭지점 (최소 3개) */
    points: GeoPoint[];
}
/**
 * near / box / polygon 중 정확히 하나를 지정한다.
 */
interface GeoQuery {
    near?: GeoNear;
    box?: GeoBoundingBox;
    polygon?: GeoPolygon;
}
interface GeoResult {
    id: string;
    data: Record<string, unknown>;
    distance: number;
}
interface GeoResponse {
    results: GeoResult[];
    total_count: number;
}
type AtomicOperatorType = "increment" | "serverTimestamp" | "deleteField" | "arrayUnion" | "arrayRemove" | "arrayPush" | "min" | "max" | "objectMerge" | "objectSet" | "geoPoint";
interface AtomicOperator {
    type: AtomicOperatorType;
    value?: unknown;
}
interface BatchOperation {
    type: "create" | "update" | "delete";
    table_id: string;
    doc_id?: string;
    data?: Record<string, unknown>;
    operators?: Record<string, AtomicOperator>;
}
interface TransactionRead {
    table_id: string;
    doc_id: string;
    alias?: string;
}
interface TransactionWrite {
    type: "create" | "update" | "delete";
    table_id: string;
    doc_id?: string;
    data?: Record<string, unknown>;
    operators?: Record<string, AtomicOperator>;
    precondition?: {
        version?: number;
        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;
    enabled: boolean;
}
interface RetentionPolicy {
    table_name: string;
    retention_days: number;
    date_field?: string;
    action: "delete" | "archive";
    archive_table?: string;
    schedule?: string;
    enabled: boolean;
}
/** 데이터베이스 실시간 구독 변경 타입 */
type DatabaseChangeType = "added" | "modified" | "removed";
/** 데이터베이스 실시간 변경 이벤트 */
interface DatabaseChange {
    type: DatabaseChangeType;
    doc_id: string;
    data?: Record<string, unknown>;
    old_data?: Record<string, unknown>;
    metadata?: {
        has_pending_writes: boolean;
        updated_at: string;
    };
}
/** 데이터베이스 실시간 스냅샷 */
interface DatabaseSnapshot {
    id: string;
    data: Record<string, unknown> | null;
    exists: boolean;
    metadata?: {
        updated_at: string;
    };
}
/** 데이터베이스 실시간 구독 옵션 */
interface DatabaseSubscribeOptions {
    /** 특정 문서 ID만 구독 */
    docId?: string;
    /** 쿼리 필터 조건 */
    where?: DatabaseRealtimeFilter[];
    /** true면 자기 변경도 수신 (기본: false) */
    includeSelf?: boolean;
    /** 메타데이터 변경도 수신 (기본: false) */
    includeMetadataChanges?: boolean;
}
/** 데이터베이스 실시간 필터 조건 */
interface DatabaseRealtimeFilter {
    field: string;
    operator: "==" | "!=" | ">" | ">=" | "<" | "<=" | "in";
    value: unknown;
}
/** 데이터베이스 실시간 스냅샷 메시지 */
interface DatabaseSnapshotMessage {
    subscription_id: string;
    docs: DatabaseSnapshot[];
    total_count: number;
    has_more: boolean;
    /** 다음 페이지 offset (has_more가 true일 때만 존재) */
    next_offset?: number;
}
/** 데이터베이스 실시간 변경 메시지 */
interface DatabaseChangeMessage {
    subscription_id: string;
    changes: DatabaseChange[];
}
/** 데이터베이스 실시간 구독 핸들러 */
interface DatabaseRealtimeHandlers {
    /** 초기 스냅샷 수신 시 */
    onSnapshot?: (docs: DatabaseSnapshot[], info: {
        totalCount: number;
        hasMore: boolean;
        nextOffset?: number;
    }) => void;
    /** 변경 이벤트 수신 시 */
    onChange?: (changes: DatabaseChange[]) => void;
    /** 에러 발생 시 */
    onError?: (error: Error) => void;
}
/** 데이터베이스 실시간 구독 객체 */
interface DatabaseRealtimeSubscription {
    /** 구독 ID */
    subscriptionId: string;
    /** 구독 해제 */
    unsubscribe(): void;
    /** 다음 페이지 스냅샷 로드 (has_more가 true일 때 사용) */
    loadMore(offset: number, limit?: number): void;
}
/** 데이터베이스 실시간 연결 옵션 */
interface DatabaseRealtimeConnectOptions {
    /**
     * 액세스 토큰 (필수). 두 종류를 모두 지원:
     *   - 앱 멤버(AppMember) JWT — 자기 앱의 테이블 구독
     *   - cross-app OAuth access token — Provider 앱의 테이블 구독 (`database:read` scope 필요)
     */
    accessToken: string;
    /** data-server URL (기본: baseUrl) */
    dataServerUrl?: string;
    /** 자동 재연결 최대 시도 (기본: 5) */
    maxRetries?: number;
    /** 재연결 간격 밀리초 (기본: 1000) */
    retryInterval?: number;
    /** 디버그 로깅 (기본: false) */
    debug?: boolean;
}
interface CreateBackupRequest {
    /** 백업 이름 */
    name: string;
    /** 특정 테이블만 백업 (비어있으면 전체) */
    tables?: string[];
    /** gzip 압축 여부 */
    compress?: boolean;
    /** AES-256-GCM 암호화 여부 (SECRET_ENCRYPTION_KEY 필요) */
    encrypt?: boolean;
}
interface BackupInfo {
    id: string;
    app_id: string;
    name: string;
    type: string;
    status: "pending" | "completed" | "failed" | "in_progress";
    tables: string[];
    storage_path?: string;
    size_bytes?: number;
    compressed: boolean;
    encrypted: boolean;
    completed_at?: string;
    error_message?: string;
    metadata?: Record<string, unknown>;
    created_at: string;
    updated_at: string;
}
interface RestoreBackupRequest {
    /** 백업 ID */
    backup_id: string;
    /** 특정 테이블만 복원 (비어있으면 전체) */
    tables?: string[];
    /** 복원 모드: replace (기존 삭제 후 삽입, 기본) 또는 merge (기존 유지) */
    mode?: "replace" | "merge";
}
interface RestoreBackupResponse {
    success: boolean;
    tables_restored: number;
    rows_restored: number;
    message?: string;
    errors?: string[];
}
interface ExportDataRequest {
    /** 내보낼 테이블 이름 (비어있으면 전체) */
    tables?: string[];
    /** 내보내기 형식 */
    format?: "json" | "csv" | "ndjson";
    /** 스키마 포함 여부 */
    include_schema?: boolean;
}
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, {
        rows: Record<string, unknown>[];
    }>;
    /** 가져오기 모드: merge (기본), replace, skip */
    mode?: "merge" | "replace" | "skip";
    /** 시뮬레이션만 수행 */
    dry_run?: boolean;
}
interface ImportDataResponse {
    success: boolean;
    rows_imported: number;
    rows_skipped: number;
    rows_failed: number;
    errors?: string[];
}
interface CopyTableRequest {
    /** 원본 테이블 이름 */
    source_table: string;
    /** 대상 테이블 이름 */
    target_table: string;
    /** 데이터 복사 여부 (기본: true) */
    copy_data?: boolean;
    /** 스키마 복사 여부 (기본: true) */
    copy_schema?: boolean;
}
interface CopyTableResponse {
    success: boolean;
    source_table: string;
    target_table: string;
    table_id: string;
    rows_copied: number;
    message?: string;
}
interface MigrateDataRequest {
    /** 원본 테이블 이름 */
    source_table: string;
    /** 대상 테이블 이름 */
    target_table: string;
    /** 필드 매핑: { "old_field": "new_field", ... } */
    transform?: Record<string, string>;
    /** 필터 조건: { "field": "value", ... } */
    filter?: Record<string, unknown>;
    /** 마이그레이션 후 원본 삭제 */
    delete_source?: boolean;
    /** 시뮬레이션만 수행 */
    dry_run?: boolean;
}
interface MigrateDataResponse {
    success: boolean;
    rows_migrated: number;
    rows_deleted?: number;
    rows_failed: number;
    errors?: string[];
}
interface SearchIndex {
    id: string;
    table_id: string;
    name: string;
    fields: string[];
    weights?: Record<string, number>;
    synonyms?: string[][];
    language?: string;
    min_length?: number;
    created_at: string;
    updated_at?: string;
}
interface CreateSearchIndexRequest {
    name: string;
    fields: string[];
    weights?: Record<string, number>;
    synonyms?: string[][];
    language?: string;
    min_length?: number;
}
interface GeoIndex {
    id: string;
    table_id: string;
    field: string;
    precision?: number;
    created_at: string;
    updated_at?: string;
}
interface CreateGeoIndexRequest {
    field: string;
    precision?: number;
}
interface ArchivePolicy {
    table_name: string;
    condition: Record<string, unknown>;
    destination_table: string;
    schedule?: string;
    delete_after_archive?: boolean;
    enabled: boolean;
}
interface LifecyclePolicy {
    id: string;
    type: "ttl" | "retention" | "archive";
    table_name: string;
    enabled: boolean;
    config: Record<string, unknown>;
    created_at: string;
    updated_at?: string;
}

declare class DatabaseAPI {
    private http;
    private realtimeWs;
    private realtimeState;
    private realtimeHandlers;
    private realtimeRetryCount;
    private realtimeOptions;
    private pendingRequests;
    private pingInterval;
    private realtimeOnStateChange;
    private realtimeOnError;
    private activeSubscriptions;
    constructor(http: HttpClient);
    /**
     * Database 공개 API 접두사.
     *
     * 서버의 테이블/컬럼/데이터 CRUD 는 모두 `/v1/public/*` 경로에서만 제공되며
     * (core-server → data-server 프록시), JWT 기반 `/v1/*` 경로는 존재하지 않습니다.
     * 따라서 항상 `/v1/public` 을 사용합니다. 인증은 `X-Public-Key` 헤더에
     * `publicKey` (`cb_pk_*`) 를 실어 서버가 검증합니다.
     */
    private getPublicPrefix;
    /**
     * 테이블 목록 조회
     */
    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` 로 매핑됩니다.
     */
    updateTable(tableId: string, data: Partial<CreateTableRequest>): 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<void>;
    /**
     * 컬럼 수정.
     *
     * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
     */
    updateColumn(tableId: string, columnName: string, data: UpdateColumnRequest): Promise<void>;
    /**
     * 컬럼 삭제
     */
    deleteColumn(tableId: string, columnName: string): Promise<void>;
    /**
     * 데이터 조회 (페이지네이션)
     */
    getData(tableId: string, options?: QueryOptions): Promise<FetchDataResponse>;
    /**
     * 조건부 데이터 조회 (Where, OrderBy, Select, Exclude)
     */
    queryData(tableId: string, options: QueryOptions): Promise<FetchDataResponse>;
    /**
     * 단일 데이터 조회
     */
    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(tableIdOrName: string, data: CreateDataRequest, options?: {
        autoCreate?: boolean;
    }): Promise<DataItem>;
    /**
     * 데이터 수정 (부분 업데이트)
     * 제공된 필드만 수정되고, 기존 필드는 유지됩니다.
     */
    updateData(tableId: string, dataId: string, data: UpdateDataRequest): Promise<DataItem>;
    /**
     * 데이터 삭제
     */
    deleteData(tableId: string, dataId: string): Promise<void>;
    /**
     * 여러 데이터 한번에 생성 (Bulk Create)
     */
    createMany(tableId: string, items: CreateDataRequest[]): Promise<BulkCreateResponse>;
    /**
     * 조건에 맞는 데이터 삭제
     */
    deleteWhere(tableId: string, where: WhereCondition): Promise<DeleteWhereResponse>;
    /**
     * 집계 파이프라인 실행 (MongoDB 스타일)
     */
    aggregate(tableId: string, pipeline: AggregateStage[]): Promise<AggregateResult>;
    /**
     * 전문 검색
     */
    search(tableId: string, query: string, fields: string[], options?: SearchOptions): Promise<SearchResponse>;
    /**
     * 자동완성 검색
     */
    autocomplete(tableId: string, query: string, field: string, options?: {
        limit?: number;
    }): Promise<SearchResponse>;
    /**
     * 지리 쿼리 (반경, 박스, 폴리곤)
     */
    geoQuery(tableId: string, field: string, query: GeoQuery, options?: {
        limit?: number;
        offset?: number;
    }): Promise<GeoResponse>;
    /**
     * 배치 쓰기 (여러 테이블 다중 문서 원자적 처리)
     *
     * 서버는 HTTP 200 + `success:false` + 개별 op `error` 로 부분 실패를 표현한다.
     * SDK 는 호출자가 silent success 로 오해하지 않도록 첫 실패 op 의 메시지로 throw 한다.
     */
    batch(operations: BatchOperation[]): Promise<BatchWriteResult>;
    /**
     * 트랜잭션 실행 (읽기 → 쓰기 ACID)
     *
     * 서버는 부분 실패가 없는 ACID 트랜잭션을 보장하지만, 검증/RLS/충돌은
     * `success:false` + `error` 로 알린다. SDK 는 silent success 회귀 방지 차원에서 throw.
     */
    transaction(reads: TransactionRead[], writes: TransactionWrite[]): Promise<TransactionResult>;
    /**
     * 데이터 조회 시 릴레이션 로딩 (JOIN)
     */
    getDataWithPopulate(tableId: string, options: QueryOptions & {
        populate: PopulateOption[];
    }): Promise<FetchDataResponse>;
    /**
     * 보안 규칙 목록 조회
     */
    listSecurityRules(appId: string): Promise<SecurityRule[]>;
    /**
     * 보안 규칙 생성
     */
    createSecurityRule(appId: string, data: CreateSecurityRuleRequest): Promise<SecurityRule>;
    /**
     * 보안 규칙 수정
     */
    updateSecurityRule(appId: string, ruleId: string, data: UpdateSecurityRuleRequest): Promise<SecurityRule>;
    /**
     * 보안 규칙 삭제
     */
    deleteSecurityRule(appId: string, ruleId: string): Promise<void>;
    /**
     * 테이블 인덱스 목록 조회
     */
    listIndexes(appId: string, tableId: string): Promise<TableIndex[]>;
    /**
     * 인덱스 생성
     */
    createIndex(appId: string, tableId: string, data: CreateIndexRequest): Promise<TableIndex>;
    /**
     * 인덱스 삭제
     */
    deleteIndex(appId: string, tableId: string, indexId: string): Promise<void>;
    /**
     * 인덱스 분석 및 추천
     */
    analyzeIndexes(appId: string, tableId: string): Promise<IndexAnalysis>;
    listSearchIndexes(appId: string, tableId: string): Promise<SearchIndex[]>;
    createSearchIndex(appId: string, tableId: string, data: CreateSearchIndexRequest): Promise<SearchIndex>;
    deleteSearchIndex(appId: string, tableId: string, indexId: string): Promise<void>;
    listGeoIndexes(appId: string, tableId: string): Promise<GeoIndex[]>;
    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, sourceTable?: string): Promise<TableRelation[]>;
    /**
     * 릴레이션 생성.
     *
     * 서버 경로: `POST /v1/apps/:appID/databases/relations` — body 내 `source_table`/`target_table` 로 테이블 지정.
     */
    createRelation(appId: string, data: CreateRelationRequest): Promise<TableRelation>;
    /**
     * 릴레이션 삭제. `relationId` 는 서버에서 발급한 UUID (listRelations 로 조회해 얻음).
     *
     * 서버 경로: `DELETE /v1/apps/:appID/databases/relations/:relationID`
     */
    deleteRelation(appId: string, relationId: string): Promise<void>;
    /**
     * 트리거 목록 조회
     */
    listTriggers(appId: string): Promise<Trigger[]>;
    /**
     * 트리거 생성
     */
    createTrigger(appId: string, data: CreateTriggerRequest): Promise<Trigger>;
    /**
     * 트리거 수정
     */
    updateTrigger(appId: string, triggerId: string, data: UpdateTriggerRequest): Promise<Trigger>;
    /**
     * 트리거 삭제
     */
    deleteTrigger(appId: string, triggerId: string): Promise<void>;
    /**
     * TTL 정책 설정
     */
    setTTL(appId: string, config: TTLConfig): Promise<TTLConfig>;
    /**
     * TTL 정책 조회
     */
    getTTL(appId: string, tableName: string): Promise<TTLConfig>;
    /**
     * 보관 정책 설정
     */
    setRetentionPolicy(appId: string, policy: RetentionPolicy): Promise<RetentionPolicy>;
    /**
     * 보관 정책 조회
     */
    getRetentionPolicy(appId: string, tableName: string): Promise<RetentionPolicy>;
    setArchivePolicy(appId: string, policy: ArchivePolicy): Promise<ArchivePolicy>;
    getArchivePolicy(appId: string, tableName: string): Promise<ArchivePolicy>;
    executeTTL(appId: string, tableName: string): Promise<{
        deleted: number;
    }>;
    executeArchive(appId: string, tableName: string): Promise<{
        archived: number;
    }>;
    executeRetention(appId: string, tableName: string): Promise<{
        deleted: number;
    }>;
    listPolicies(appId: string): Promise<LifecyclePolicy[]>;
    deletePolicy(appId: string, policyId: string): Promise<void>;
    generateTypes(appId: string): Promise<string>;
    listBackups(appId: string): Promise<{
        backups: BackupInfo[];
        total_count: number;
    }>;
    createBackup(appId: string, data: CreateBackupRequest): Promise<BackupInfo>;
    getBackup(appId: string, backupId: string): Promise<BackupInfo>;
    deleteBackup(appId: string, backupId: string): Promise<void>;
    restoreBackup(appId: string, backupId: string, options?: RestoreBackupRequest): Promise<RestoreBackupResponse>;
    exportData(appId: string, options?: ExportDataRequest): Promise<ExportDataResponse>;
    importData(appId: string, data: ImportDataRequest): Promise<ImportDataResponse>;
    copyTable(appId: string, data: CopyTableRequest): Promise<CopyTableResponse>;
    migrateData(appId: string, data: MigrateDataRequest): Promise<MigrateDataResponse>;
    /**
     * 데이터베이스 실시간 연결
     * 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) => {
     *         console.log('Initial data:', docs, 'total:', info.totalCount)
     *     },
     *     onChange: (changes) => {
     *         changes.forEach(change => {
     *             console.log(change.type, change.doc_id, change.data)
     *         })
     *     },
     *     onError: (error) => console.error(error)
     * })
     *
     * // 구독 해제
     * sub.unsubscribe()
     *
     * // 연결 해제
     * cb.database.disconnectRealtime()
     * ```
     */
    connectRealtime(options: DatabaseRealtimeConnectOptions): Promise<void>;
    /**
     * 데이터베이스 실시간 연결 해제
     */
    disconnectRealtime(): void;
    /**
     * 테이블 또는 문서의 실시간 변경 구독
     *
     * @param tableId 구독할 테이블 이름
     * @param handlers 이벤트 핸들러 (onSnapshot, onChange, onError)
     * @param options 구독 옵션 (docId, where, includeSelf 등)
     * @returns 구독 해제 가능한 객체
     */
    subscribe(tableId: string, handlers: DatabaseRealtimeHandlers, options?: DatabaseSubscribeOptions): DatabaseRealtimeSubscription;
    /**
     * 실시간 연결 상태 확인
     */
    isRealtimeConnected(): boolean;
    /**
     * 실시간 연결 상태 반환
     */
    getRealtimeState(): "disconnected" | "connecting" | "connected";
    /**
     * 상태 변경 콜백 등록
     */
    onRealtimeStateChange(handler: (state: "disconnected" | "connecting" | "connected") => void): () => void;
    /**
     * 에러 콜백 등록
     */
    onRealtimeError(handler: (error: Error) => void): () => void;
    private setRealtimeState;
    private doRealtimeConnect;
    /**
     * 서버에 subscribe 메시지를 보내고 서버 subscription_id를 반환하는 Promise
     */
    private sendSubscribeRequest;
    /**
     * 재연결 후 모든 활성 구독을 서버에 다시 등록
     */
    private resubscribeAll;
    private handleRealtimeMessage;
    private attemptRealtimeReconnect;
    private startRealtimePing;
    private stopRealtimePing;
    private sendRealtimeMessage;
    private generateRequestId;
    private debugLog;
}

/**
 * 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 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 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, 백엔드 워커, 로깅) 에 넘기거나
     * 디버깅 용도일 때 사용.
     *
     * ⚠️ **`<img src>` / 네이티브 `WebSocket` / `<script src>` / `EventSource` 처럼
     * 커스텀 헤더를 못 보내는 브라우저 API 에 직접 넘기면 401 입니다.** ConnectBase
     * 프록시는 모든 요청에 `X-Public-Key` 헤더를 요구하고, 쿼리 파라미터 폴백은
     * 제공하지 않습니다. 그런 경우엔 `call()` 로 받아서 Blob URL 로 변환하세요.
     *
     * @example URL 을 워커로 넘겨 호출 (✅)
     * ```typescript
     * sw.postMessage({
     *     url: cb.endpoint.url("comfyui-main", "/prompt"),
     *     key: publicKey, // 워커가 X-Public-Key 헤더로 부착
     * })
     * ```
     *
     * @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)
     * ```
     */
    url(label: string, path: string): string;
    /**
     * 같은 endpoint 호출을 `predicate` 가 값을 반환할 때까지 주기적으로 반복.
     * ComfyUI `/history/{id}`, A1111 `/sdapi/v1/progress`, 자체 큐 API 처럼
     * "작업 제출 → 폴링" 패턴을 한 줄로 처리하기 위한 헬퍼.
     *
     * 동작:
     *  - `call(label, init)` → predicate(response) 호출
     *  - predicate 가 `undefined` 면 `intervalMs` 만큼 대기 후 재시도
     *  - predicate 가 값을 반환하면 그 값을 즉시 resolve
     *  - `timeoutMs` 초과 또는 `signal` abort 시 reject
     *  - HTTP 5xx/네트워크 오류는 재시도, 4xx 는 즉시 reject (작업 자체가 잘못된 경우)
     *
     * predicate 는 같은 Response 를 한 번만 읽을 수 있으므로, 헬퍼 내부에서
     * `res.clone().json()` 형태로 안전하게 파싱한 뒤 호출자에게 전달.
     *
     * predicate 의 `body` 는 `unknown` 으로 전달되므로, 호출자가 자신의 응답
     * 스키마로 narrowing 한 뒤 사용한다 (런타임 검증 책임은 호출자에게 있음).
     *
     * @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}` },
     *     (body) => {
     *         const data = body as 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 },
     * )
     * ```
     */
    /**
     * 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.
     *
     * Both the client→upstream and upstream→client byte streams flow
     * transparently — the proxy server adds no framing of its own.
     *
     * @example ComfyUI native event channel
     * ```ts
     * const ws = await cb.endpoint.connectWebSocket("comfyui-main", {
     *     path: "/ws",
     *     query: { clientId: crypto.randomUUID() },
     * })
     * 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
     *     }
     * }
     * ```
     */
    connectWebSocket(label: string, opts?: ConnectWebSocketOptions): Promise<WebSocket>;
    pollUntil<T>(label: string, init: EndpointCallInit, predicate: (body: unknown, res: Response) => T | undefined | Promise<T | undefined>, opts?: PollUntilOptions): Promise<T>;
}
/**
 * EndpointAPI.call 의 init 인자.
 *
 * 표준 RequestInit 와 거의 동일하지만 `path` 가 필수 (URL 은 SDK 가 조립).
 */
interface EndpointCallInit {
    /**
     * 사용자 모델 서버의 엔드포인트 경로. 반드시 `/` 로 시작.
     * 예: `"/prompt"`, `"/v1/chat/completions"`, `"/sdapi/v1/txt2img"`.
     */
    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;
}

type ErrorType = "error" | "unhandledrejection" | "resource" | "network" | "custom";
interface ErrorReport {
    message: string;
    source?: string;
    lineno?: number;
    colno?: number;
    stack?: string;
    error_type?: ErrorType;
    url?: string;
    referrer?: string;
}
interface ErrorTrackerConfig {
    /**
     * 에러 자동 캡처 활성화 여부
     * @default true
     */
    autoCapture?: boolean;
    /**
     * 캡처할 에러 타입
     * @default ['error', 'unhandledrejection']
     */
    captureTypes?: ErrorType[];
    /**
     * 에러 배치 전송 간격 (ms)
     * @default 5000
     */
    batchInterval?: number;
    /**
     * 최대 배치 크기
     * @default 10
     */
    maxBatchSize?: number;
    /**
     * 에러 필터 함수 (false 반환 시 무시)
     */
    beforeSend?: (error: ErrorReport) => ErrorReport | false | null;
    /**
     * 디버그 모드 (콘솔 로깅)
     * @default false
     */
    debug?: boolean;
}
/**
 * 에러 트래커 API
 * 클라이언트 JavaScript 에러를 서버로 리포트합니다.
 */
declare class ErrorTrackerAPI {
    private http;
    private storageWebId;
    private config;
    private errorQueue;
    private batchTimer;
    private isInitialized;
    private originalOnError;
    private originalOnUnhandledRejection;
    constructor(http: HttpClient, config?: ErrorTrackerConfig);
    /**
     * 에러 트래커 초기화
     * @param storageWebId 웹 스토리지 ID
     */
    init(storageWebId: string): void;
    /**
     * 에러 트래커 정리 (언마운트 시 호출)
     */
    destroy(): void;
    /**
     * 수동으로 에러 리포트
     */
    captureError(error: Error | string, extra?: Partial<ErrorReport>): Promise<void>;
    /**
     * 커스텀 에러 리포트
     */
    captureMessage(message: string, extra?: Partial<ErrorReport>): Promise<void>;
    /**
     * 큐에 있는 에러들 즉시 전송
     */
    flush(): Promise<void>;
    private log;
    private setupAutoCapture;
    private removeAutoCapture;
    private handleGlobalError;
    private handleUnhandledRejection;
    private createErrorReport;
    private queueError;
    private startBatchTimer;
    private stopBatchTimer;
    private flushQueue;
}

/**
 * 함수 실행 요청
 */
interface InvokeFunctionRequest {
    /** 함수에 전달할 데이터 */
    payload?: Record<string, unknown>;
    /** 실행 타임아웃 (초) */
    timeout?: number;
}
/**
 * 함수 실행 응답
 */
interface InvokeFunctionResponse {
    /** 실행 성공 여부 */
    success: boolean;
    /** 실행 ID */
    execution_id: string;
    /** 함수 실행 결과 */
    result?: Record<string, unknown>;
    /** 실행 시간 (밀리초) */
    duration: number;
    /** 실행 상태 ('success' | 'error' | 'timeout') */
    status: "success" | "error" | "timeout";
    /** 에러 메시지 (실패 시) */
    error?: string;
}

declare class FunctionsAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * 서버리스 함수 실행
     *
     * @param functionId - 함수 ID
     * @param payload - 함수에 전달할 데이터 (선택)
     * @param timeout - 실행 타임아웃 (초, 선택)
     * @returns 함수 실행 결과
     *
     * @example
     * ```typescript
     * // 기본 실행
     * const result = await cb.functions.invoke('function-id')
     *
     * // 데이터와 함께 실행
     * const result = await cb.functions.invoke('function-id', {
     *     name: 'John',
     *     age: 30
     * })
     *
     * // 타임아웃 설정
     * const result = await cb.functions.invoke('function-id', { data: 'test' }, 60)
     * ```
     */
    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>;
    /**
     * 서버리스 함수 실행 (비동기 래퍼)
     * 결과만 반환하고 메타데이터는 제외
     *
     * @param functionId - 함수 ID
     * @param payload - 함수에 전달할 데이터 (선택)
     * @returns 함수 실행 결과 데이터
     *
     * @example
     * ```typescript
     * const data = await cb.functions.call('function-id', { name: 'John' })
     * console.log(data) // 함수가 반환한 데이터
     * ```
     */
    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;
}

/**
 * Game Server Types
 */

/**
 * 게임 룸 설정
 */
interface GameRoomConfig {
    /** 룸 ID (선택사항, 미지정시 자동 생성) */
    roomId?: string;
    /** 카테고리 ID (선택사항) */
    categoryId?: string;
    /** 틱 레이트 (TPS, 기본 64) */
    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>;
}
/**
 * 게임 플레이어 정보
 */
interface GamePlayer {
    clientId: string;
    userId?: string;
    joinedAt: number;
    metadata?: Record<string, string>;
}
/**
 * 게임 상태
 */
interface GameState {
    roomId: string;
    state: Record<string, unknown>;
    version: number;
    serverTime: number;
    tickRate: number;
    players: GamePlayer[];
}
/**
 * 상태 변경 (델타)
 */
interface StateChange {
    path: string;
    operation: "set" | "delete";
    value?: unknown;
    oldValue?: unknown;
}
/**
 * 게임 델타 업데이트
 */
interface GameDelta {
    fromVersion: number;
    toVersion: number;
    changes: StateChange[];
    tick: number;
}
/**
 * 게임 액션
 */
interface GameAction {
    type: string;
    data?: unknown;
    clientTimestamp?: number;
    sequence?: number;
}
/**
 * 룸 정보
 */
interface GameRoomInfo {
    id: string;
    appId: string;
    categoryId?: string;
    playerCount: number;
    maxPlayers: number;
    tickRate: number;
    isRunning: boolean;
    createdAt: number;
    metadata?: Record<string, string>;
}
/**
 * 게임 서버 메시지 타입
 */
type GameServerMessageType = "room_created" | "room_joined" | "room_left" | "state" | "delta" | "player_event" | "chat" | "pong" | "room_list" | "error" | "room_stale" | "sync_lost";
/**
 * 게임 서버 메시지
 * 서버는 모든 필드를 최상위에 보냄 (data 래퍼 없음)
 */
interface GameServerMessage {
    type: GameServerMessageType;
    msg_id?: string;
    room_id?: string;
    server_time?: number;
    delta?: {
        from_version: number;
        to_version: number;
        changes: {
            path: string;
            operation: string;
            value?: unknown;
            old_value?: unknown;
        }[];
        tick: number;
    };
    tick?: number;
    event?: string;
    player?: {
        client_id: string;
        user_id?: string;
        joined_at: number;
        metadata?: Record<string, string>;
    };
    client_id?: string;
    user_id?: string;
    message?: string;
    data?: unknown;
    code?: string;
    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;
}
/**
 * 플레이어 이벤트
 */
interface PlayerEvent {
    event: "joined" | "left";
    roomId: string;
    player: GamePlayer;
    serverTime: number;
}
/**
 * 채팅 메시지
 */
interface ChatMessage {
    roomId: string;
    clientId: string;
    userId?: string;
    message: string;
    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: 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 응답
 */
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;
    /**
     * - `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: {
        type: string;
        clientId: string;
        data?: unknown;
        timestamp: number;
    }) => void;
    onPlayerJoined?: (player: GamePlayer) => void;
    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;
}
/**
 * 게임 클라이언트 설정
 */
interface GameClientConfig {
    /** 게임 서버 URL */
    gameServerUrl?: string;
    /** 앱 ID */
    appId?: string;
    /** Public Key */
    publicKey?: string;
    /** 액세스 토큰 */
    accessToken?: string;
    /** 클라이언트 ID */
    clientId: string;
    /** 자동 재연결 여부 */
    autoReconnect?: boolean;
    /** 재연결 최대 시도 횟수 */
    maxReconnectAttempts?: number;
    /** 재연결 간격 (ms) */
    reconnectInterval?: number;
    /** 연결 타임아웃 (ms) */
    connectionTimeout?: number;
}
/**
 * 게임 연결 상태
 */
type GameConnectionStatus = "disconnected" | "connecting" | "connected" | "reconnecting" | "error";
/**
 * 게임 연결 상태 정보
 */
interface GameConnectionState {
    status: GameConnectionStatus;
    transport: "webtransport" | "websocket" | null;
    roomId: string | null;
    latency: number | null;
    reconnectAttempt?: number;
    lastError?: Error;
}
/**
 * 매치메이킹 큐 참가 요청
 */
interface JoinQueueRequest {
    gameType: string;
    playerId: string;
    rating?: number;
    region?: string;
    mode?: "ranked" | "quick_play" | "custom";
    partyMembers?: string[];
    metadata?: Record<string, string>;
}
/**
 * 매치메이킹 티켓
 */
interface MatchmakingTicket {
    ticketId: string;
    gameType: string;
    playerId: string;
    status: string;
    createdAt: string;
    waitTime?: number;
    matchId?: string;
    roomId?: string;
}
/**
 * 로비 가시성
 */
type LobbyVisibility = "public" | "private" | "friends_only";
/**
 * 로비 생성 요청
 */
interface CreateLobbyRequest {
    playerId: string;
    displayName?: string;
    name: string;
    gameType?: string;
    password?: string;
    maxPlayers?: number;
    visibility?: LobbyVisibility;
    region?: string;
    settings?: Record<string, unknown>;
    tags?: string[];
}
/**
 * 로비 멤버
 */
interface LobbyMember {
    playerId: string;
    displayName: string;
    role: string;
    team: string;
    ready: boolean;
    slot: number;
    joinedAt: string;
}
/**
 * 로비 정보
 */
interface LobbyInfo {
    id: string;
    name: string;
    hostId: string;
    gameType: string;
    playerCount: number;
    maxPlayers: number;
    hasPassword: boolean;
    visibility: LobbyVisibility;
    region: string;
    settings?: Record<string, unknown>;
    tags?: string[];
    status: string;
    roomId?: string;
    members?: LobbyMember[];
    createdAt: string;
}
/**
 * 로비 업데이트 요청
 */
interface UpdateLobbyRequest {
    hostId: string;
    name?: string;
    maxPlayers?: number;
    visibility?: LobbyVisibility;
    password?: string;
    settings?: Record<string, unknown>;
    tags?: string[];
}
/**
 * 로비 초대 정보
 */
interface LobbyInvite {
    inviteId: string;
    lobbyId: string;
    lobbyName: string;
    inviterId: string;
    inviteeId: string;
    status: string;
    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;
}

/**
 * 게임 서버 기능 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_enabled")
     */
    enable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
    /**
     * 단일 기능 비활성화.
     */
    disable(appId: string, feature: keyof GameConfig): Promise<GameConfig>;
    private resolveAppId;
}

/**
 * 게임 서버 `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 연결을 관리하고 게임 상태를 동기화합니다.
 */
declare class GameRoom {
    private ws;
    private config;
    private handlers;
    private reconnectAttempts;
    private reconnectTimer;
    private pingInterval;
    private actionSequence;
    private _roomId;
    private _state;
    private _scriptName;
    private _scriptVersion;
    private _isConnected;
    constructor(config: GameClientConfig);
    /**
     * 현재 룸 ID
     */
    get roomId(): string | null;
    /**
     * 현재 게임 상태
     */
    get state(): GameState | null;
    /**
     * 연결 상태
     */
    get isConnected(): boolean;
    /**
     * 이벤트 핸들러 등록
     */
    on<K extends keyof GameEventHandlers>(event: K, handler: GameEventHandlers[K]): this;
    /**
     * 게임 서버에 연결
     */
    connect(roomId?: string): Promise<void>;
    /**
     * 연결 해제
     */
    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;
    /**
     * 룸 참가
     */
    joinRoom(roomId: string, metadata?: Record<string, string>): Promise<GameState>;
    /**
     * 룸 퇴장
     */
    leaveRoom(): Promise<void>;
    /**
     * 게임 액션 전송
     */
    sendAction(action: GameAction): void;
    /**
     * 채팅 메시지 전송
     */
    sendChat(message: string): void;
    /**
     * 현재 상태 요청
     */
    requestState(): Promise<GameState>;
    /**
     * 룸 목록 조회
     */
    listRooms(): Promise<GameRoomInfo[]>;
    /**
     * Ping 전송 (RTT 측정용)
     */
    ping(): Promise<number>;
    private buildConnectionUrl;
    private msgIdCounter;
    private send;
    private sendWithHandler;
    private handleMessage;
    private handleDelta;
    private applyChange;
    private handlePlayerEvent;
    private scheduleReconnect;
    private startPingInterval;
    private stopPingInterval;
}
/**
 * 게임 API
 * HTTP 기반 게임 서버 관리 API
 */
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;
    /**
     * 룸 목록 조회 (HTTP)
     */
    listRooms(appId?: string): Promise<GameRoomInfo[]>;
    /**
     * 룸 상세 조회 (HTTP)
     */
    getRoom(roomId: string): Promise<GameRoomInfo>;
    /**
     * 룸 생성 (HTTP, gRPC 대안)
     *
     * @deprecated 현재 SDK public 경로로 노출되지 않습니다. 콘솔(admin) 에서 진행하거나 백엔드 public 경로 오픈을 요청하세요.
     */
    createRoom(_appId: string, _config?: GameRoomConfig): Promise<GameRoomInfo>;
    /**
     * 룸 삭제 (HTTP)
     *
     * @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 이면 만료 없음.
     */
    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")
     */
    listMatchqueue(appId: string, queueKey: string): Promise<MatchqueueListResponse>;
    /**
     * 매칭 큐에서 ticket 제거 (예: 사용자가 매칭 취소).
     */
    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")
     */
    submitScore(appId: string, leaderboardKey: string, member: string, score: number, mode?: "set" | "incr"): Promise<LeaderboardScoreEntry>;
    /**
     * 상위 n 명 조회 (기본 10).
     */
    getTopScores(appId: string, leaderboardKey: string, n?: number): Promise<LeaderboardListResponse>;
    /**
     * 단일 member 의 rank + score.
     */
    getMemberRank(appId: string, leaderboardKey: string, member: string): Promise<LeaderboardScoreEntry>;
    /**
     * member 주변 (위 above 명 + 본인 + 아래 below 명) 조회.
     */
    getRankAround(appId: string, leaderboardKey: string, member: string, above?: number, below?: number): Promise<LeaderboardListResponse>;
    /**
     * leaderboard 전체 reset (시즌 종료 시).
     */
    resetLeaderboard(appId: string, leaderboardKey: string): Promise<void>;
    /**
     * 특정 member 만 제거 (계정 삭제 등).
     */
    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"))
     */
    uploadScript(appId: string, name: string, code: string): Promise<ScriptVersion>;
    /**
     * app 의 모든 스크립트 메타데이터 목록.
     */
    listScripts(appId: string): Promise<ScriptListResponse>;
    /**
     * 단일 스크립트 메타 + active version code.
     */
    getScript(appId: string, name: string): Promise<ScriptDetailResponse>;
    /**
     * 단일 스크립트의 모든 버전 이력.
     */
    listScriptVersions(appId: string, name: string): Promise<ScriptVersionListResponse>;
    /**
     * 특정 버전 활성화 (hot reload 자동). version=0 또는 미지정 → latest 활성화.
     */
    activateScript(appId: string, name: string, version?: number): Promise<ScriptMeta>;
    /**
     * 직전 active 버전으로 롤백 (hot reload 자동).
     */
    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.
     */
    deactivateScript(appId: string, name: string): Promise<void>;
    /**
     * 스크립트 영구 삭제 (hard-delete) — 메타 + 모든 버전 영구 제거. 복구 불가.
     *
     * 잘못 업로드된 스크립트나 더 이상 사용하지 않는 슬롯을 정리할 때 사용. 단순 비활성화는
     * {@link deactivateScript} 를 사용한다 (코드 보존, 재활성화 가능).
     *
     * v3.14.0 신규 — server 측 `DELETE /scripts/:name` 의 의미가 Disable → hard-delete 로
     * 변경된 것에 대응.
     */
    deleteScript(appId: string, name: string): Promise<void>;
}

interface CreateDocumentRequest {
    name: string;
    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;
    name: string;
    source_type: string;
    mime_type?: string;
    source_url?: string;
    external_id?: string;
    file_size: number;
    chunk_count: number;
    status: "pending" | "processing" | "ready" | "failed";
    error_message?: string;
    metadata?: Record<string, unknown>;
    knowledge_base_id: string;
    created_at: string;
    updated_at: string;
    processed_at?: string;
}
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;
    /**
     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
     */
    hybrid?: 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;
    document_id: string;
    document_name: string;
    content: string;
    title?: string;
    score: number;
    chunk_index: number;
    metadata?: Record<string, unknown>;
}
interface KnowledgeSearchResponse {
    query: string;
    results: KnowledgeSearchResult[];
    total: 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
 *
 * AI 데이터베이스를 위한 문서 저장 및 검색 API.
 * 문서를 업로드하면 자동으로 청킹되어 키워드 기반 검색이 가능합니다.
 *
 * ## 사용자별 격리 (다중 사용자 RAG 시나리오)
 *
 * `Authorization: Bearer <appmember-jwt>` 를 함께 보내면 서버가:
 * - 검색 결과를 본인 문서 (metadata.user_id == member_id) 로 제한
 * - addDocument 시 metadata.user_id 자동 태깅
 * - listDocuments / deleteDocument 도 본인 자료만 노출
 *
 * @example
 * ```typescript
 * const cb = new ConnectBase({ publicKey: 'your-public-key' })
 *
 * // 텍스트 문서 추가
 * await cb.knowledge.addDocument('kb-id', {
 *     name: '환불 정책',
 *     source_type: 'text',
 *     content: '환불은 구매 후 7일 이내에 가능합니다...'
 * })
 *
 * // 문서 검색
 * 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>;
}

/**
 * Native Bridge API
 *
 * 웹, 모바일(React Native), 데스크톱(Electron)에서 동일한 API로
 * 네이티브 기능을 사용할 수 있는 크로스 플랫폼 유틸리티
 *
 * @example
 * ```typescript
 * import ConnectBase from 'connectbase-client'
 *
 * const cb = new ConnectBase({ publicKey: 'your-public-key' })
 *
 * // 플랫폼 감지
 * const platform = cb.native.getPlatform() // 'web' | 'mobile' | 'desktop'
 *
 * // 크로스 플랫폼 클립보드
 * await cb.native.clipboard.writeText('Hello')
 *
 * // 크로스 플랫폼 파일 저장
 * await cb.native.filesystem.saveFile('Hello World', 'hello.txt')
 * ```
 */
declare global {
    interface Window {
        NativeBridge?: NativeBridgeInterface;
        ReactNativeWebView?: unknown;
    }
}
interface NativeBridgeInterface {
    platform?: "electron" | "react-native" | "ios" | "android";
    /** 실행 OS (react-native: 'ios' | 'android', electron: process.platform) */
    os?: string;
    /** 네이티브 셸에서 실행 중인지 (패키징 앱이면 항상 true) */
    isNative?: boolean;
    /** 브릿지 원시 호출 (문서화되지 않은 타입 호출용) */
    call?: (type: string, payload?: unknown, options?: {
        timeoutMs?: number;
    }) => Promise<unknown>;
    app?: {
        getVersion?: () => Promise<string>;
        getName?: () => Promise<string>;
        getInfo?: () => Promise<NativeAppInfo>;
        getPath?: (name: string) => Promise<string | null>;
        reload?: () => Promise<void>;
        quit?: () => Promise<void>;
    };
    browser?: {
        openExternal: (url: string) => Promise<{
            success: boolean;
        }>;
    };
    camera?: {
        takePicture: (options?: CameraOptions) => Promise<ImageResult>;
        pickImage: (options?: PickImageOptions) => Promise<ImageResult[]>;
    };
    push?: {
        getToken: () => Promise<{
            token: string;
            platform?: string;
        }>;
        requestPermission: () => Promise<{
            granted: boolean;
        }>;
        scheduleLocal: (options: LocalNotificationOptions) => Promise<{
            notificationId: string;
        }>;
        setBadgeCount?: (count: number) => Promise<{
            success: boolean;
        }>;
    };
    speech?: {
        recognize: (options?: SpeechRecognizeOptions) => Promise<SpeechResult>;
        stop: () => Promise<{
            stopped: boolean;
        }>;
        isAvailable: () => Promise<{
            available: boolean;
        }>;
    };
    location?: {
        getCurrentPosition: (options?: LocationOptions) => Promise<Position>;
        watchPosition: (options?: LocationOptions) => Promise<{
            watchId: string;
        }>;
        stopWatch: (watchId: string) => Promise<{
            stopped: boolean;
        }>;
    };
    biometric?: {
        isAvailable: () => Promise<BiometricInfo>;
        authenticate: (options?: BiometricOptions) => Promise<BiometricResult>;
    };
    secureStore?: {
        setItem: (key: string, value: string) => Promise<{
            success: boolean;
        }>;
        getItem: (key: string) => Promise<{
            value: string | null;
        }>;
        deleteItem: (key: string) => Promise<{
            success: boolean;
        }>;
    };
    admob?: {
        showInterstitial: () => Promise<{
            shown: boolean;
        }>;
        showRewarded: () => Promise<{
            rewarded: boolean;
        }>;
    };
    system?: {
        getInfo: () => Promise<SystemInfo>;
        getMemory: () => Promise<MemoryInfo>;
        getCPU: () => Promise<CPUInfo>;
    };
    window?: {
        minimize: () => Promise<void>;
        maximize: () => Promise<void>;
        unmaximize: () => Promise<void>;
        isMaximized: () => Promise<boolean>;
        close: () => Promise<void>;
        setTitle: (title: string) => Promise<void>;
        setSize: (width: number, height: number) => Promise<void>;
        getSize: () => Promise<[number, number]>;
        setPosition: (x: number, y: number) => Promise<void>;
        getPosition: () => Promise<[number, number]>;
        center: () => Promise<void>;
        setFullScreen: (flag: boolean) => Promise<void>;
        isFullScreen: () => Promise<boolean>;
        setAlwaysOnTop: (flag: boolean) => Promise<void>;
    };
    clipboard?: {
        readText: () => Promise<string>;
        writeText: (text: string) => Promise<void>;
        readHTML: () => Promise<string>;
        writeHTML: (html: string) => Promise<void>;
        readImage: () => Promise<string | null>;
        writeImage: (dataURL: string) => Promise<void>;
        clear: () => Promise<void>;
    };
    shell?: {
        openExternal: (url: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        openPath: (path: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        showItemInFolder: (path: string) => Promise<{
            success: boolean;
        }>;
        beep: () => Promise<void>;
    };
    notification?: {
        show: (options: NotificationOptions) => Promise<{
            success: boolean;
        }>;
        isSupported: () => Promise<boolean>;
    };
    filesystem?: {
        showOpenDialog?: (options?: OpenDialogOptions) => Promise<OpenDialogResult>;
        showSaveDialog?: (options?: SaveDialogOptions) => Promise<SaveDialogResult>;
        readFile: (path: string, encoding?: string) => Promise<{
            success: boolean;
            content?: string;
            error?: string;
        }>;
        writeFile: (path: string, content: string, encoding?: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        exists: (path: string) => Promise<boolean>;
        stat: (path: string) => Promise<FileStats>;
        readDir: (path: string) => Promise<{
            success: boolean;
            entries?: DirEntry[];
            error?: string;
        }>;
        mkdir: (path: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        remove: (path: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        copy: (src: string, dest: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        move: (src: string, dest: string) => Promise<{
            success: boolean;
            error?: string;
        }>;
        pickDocument?: (options?: PickDocumentOptions) => Promise<DocumentResult>;
        saveToGallery?: (uri: string) => Promise<{
            uri: string;
        }>;
        /** 모바일: 앱 문서/캐시 디렉터리 URI */
        getDirectories?: () => Promise<{
            document: string | null;
            cache: string | null;
        }>;
        /** 데스크톱: 접근이 허용된 앱 전용 데이터 폴더 */
        getAppDir?: () => Promise<string>;
    };
    onDeepLink?: (callback: (url: string) => void) => () => void;
}
type Platform = "web" | "mobile" | "desktop";
/** 패키징 앱 정보 (`cb.native.getAppInfo()`) */
interface NativeAppInfo {
    platform: string;
    os?: string;
    osVersion?: string;
    arch?: string;
    appVersion?: string;
    electronVersion?: string;
    webUrl?: string;
}
/** 위치 추적 핸들 (`cb.native.location.watchPosition()`) */
interface LocationWatch {
    /** 네이티브 watch 식별자 (웹 폴백에서는 geolocation watch id) */
    watchId: string;
    /** 추적 중지 */
    clear: () => Promise<void>;
}
interface CameraOptions {
    quality?: number;
    base64?: boolean;
}
interface PickImageOptions extends CameraOptions {
    multiple?: boolean;
}
interface ImageResult {
    uri: string;
    base64?: string;
    width: number;
    height: number;
}
interface LocalNotificationOptions {
    title: string;
    body: string;
    data?: Record<string, unknown>;
    trigger?: {
        seconds: number;
    } | null;
}
interface LocationOptions {
    accuracy?: "low" | "medium" | "high";
    distanceInterval?: number;
}
interface SpeechRecognizeOptions {
    /** BCP-47 언어 코드 (예: 'en-US', 'ko-KR'). 기본값 'en-US' */
    lang?: string;
    /** 중간 결과(interim) 수신 여부. 기본값 true */
    interim?: boolean;
    /** 연속 인식 여부. 기본값 false (한 문장 인식 후 종료) */
    continuous?: boolean;
    /** 중간 결과 콜백 (실시간 부분 transcript) */
    onPartial?: (transcript: string) => void;
}
interface SpeechResult {
    /** 최종 인식된 텍스트 */
    transcript: string;
    /** 최종 결과 여부 */
    isFinal: boolean;
}
interface Position {
    latitude: number;
    longitude: number;
    altitude: number | null;
    accuracy: number;
    timestamp: number;
}
interface BiometricInfo {
    available: boolean;
    hasHardware: boolean;
    isEnrolled: boolean;
    supportedTypes: number[];
}
interface BiometricOptions {
    promptMessage?: string;
    cancelLabel?: string;
    disableDeviceFallback?: boolean;
}
interface BiometricResult {
    success: boolean;
    error?: string;
}
interface SystemInfo {
    platform: string;
    arch: string;
    version: string;
    hostname: string;
    homeDir: string;
    tmpDir: string;
    cpuCount: number;
    totalMemory: number;
    freeMemory: number;
}
interface MemoryInfo {
    total: number;
    free: number;
    used: number;
    usagePercent: string;
}
interface CPUInfo {
    model: string;
    count: number;
    speed: number;
}
interface NotificationOptions {
    title: string;
    body: string;
    icon?: string;
    silent?: boolean;
}
interface OpenDialogOptions {
    title?: string;
    defaultPath?: string;
    filters?: Array<{
        name: string;
        extensions: string[];
    }>;
    properties?: Array<"openFile" | "openDirectory" | "multiSelections">;
    message?: string;
}
interface OpenDialogResult {
    canceled: boolean;
    filePaths: string[];
}
interface SaveDialogOptions {
    title?: string;
    defaultPath?: string;
    filters?: Array<{
        name: string;
        extensions: string[];
    }>;
    message?: string;
}
interface SaveDialogResult {
    canceled: boolean;
    filePath?: string;
}
interface FileStats {
    success: boolean;
    isFile?: boolean;
    isDirectory?: boolean;
    size?: number;
    created?: Date;
    modified?: Date;
    accessed?: Date;
    error?: string;
}
interface DirEntry {
    name: string;
    isFile: boolean;
    isDirectory: boolean;
}
interface PickDocumentOptions {
    type?: string;
}
interface DocumentResult {
    uri: string;
    name: string;
    size: number;
    mimeType: string;
}
/**
 * Native API - 크로스 플랫폼 네이티브 기능
 */
declare class NativeAPI {
    /** 웹 Web Speech API 인스턴스 (stop() 용) */
    private _webSpeechRecognition;
    /**
     * 현재 플랫폼 감지
     */
    getPlatform(): Platform;
    /**
     * 패키징 앱(네이티브 셸) 안에서 실행 중인지
     */
    isNativeApp(): boolean;
    /**
     * 패키징 앱 정보 조회 (웹에서는 null)
     *
     * @example
     * ```typescript
     * const info = await cb.native.getAppInfo()
     * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
     * ```
     */
    getAppInfo(): Promise<NativeAppInfo | null>;
    /**
     * 특정 네이티브 기능 지원 여부 확인
     */
    hasFeature(feature: keyof NativeBridgeInterface): boolean;
    /**
     * NativeBridge 직접 접근 (고급 사용자용)
     */
    get bridge(): NativeBridgeInterface | undefined;
    /**
     * 크로스 플랫폼 클립보드 API
     */
    clipboard: {
        /**
         * 텍스트 복사
         */
        writeText: (text: string) => Promise<void>;
        /**
         * 텍스트 읽기
         */
        readText: () => Promise<string>;
        /**
         * HTML 복사 (데스크톱 전용)
         */
        writeHTML: (html: string) => Promise<void>;
        /**
         * 이미지 복사 (데스크톱 전용, Data URL)
         */
        writeImage: (dataURL: string) => Promise<void>;
        /**
         * 이미지 읽기 (데스크톱 전용, Data URL 반환)
         */
        readImage: () => Promise<string | null>;
    };
    /**
     * 크로스 플랫폼 파일 시스템 API
     */
    filesystem: {
        /**
         * 파일 선택 다이얼로그 (데스크톱) 또는 파일 input (웹)
         */
        pickFile: (options?: {
            accept?: string;
            multiple?: boolean;
            filters?: Array<{
                name: string;
                extensions: string[];
            }>;
        }) => Promise<File[] | null>;
        /**
         * 파일 저장
         */
        saveFile: (content: string | Blob, filename: string, options?: {
            filters?: Array<{
                name: string;
                extensions: string[];
            }>;
        }) => Promise<boolean>;
        /**
         * 파일 읽기 (데스크톱/모바일)
         */
        readFile: (path: string) => Promise<string | null>;
        /**
         * 파일 존재 확인 (데스크톱/모바일)
         */
        exists: (path: string) => Promise<boolean>;
    };
    /**
     * 크로스 플랫폼 카메라/이미지 API
     */
    camera: {
        /**
         * 카메라로 사진 촬영 (모바일) 또는 파일 선택 (웹/데스크톱)
         */
        takePicture: (options?: CameraOptions) => Promise<ImageResult | null>;
        /**
         * 갤러리에서 이미지 선택
         */
        pickImage: (options?: PickImageOptions) => Promise<ImageResult[] | null>;
    };
    /**
     * 크로스 플랫폼 위치 API
     */
    location: {
        /**
         * 현재 위치 가져오기
         */
        getCurrentPosition: (options?: LocationOptions) => Promise<Position>;
        /**
         * 위치 추적 시작.
         *
         * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
         * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
         *
         * @example
         * ```typescript
         * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
         * // 나중에
         * await watch.clear()
         * ```
         */
        watchPosition: (onUpdate: (position: Position) => void, options?: LocationOptions) => Promise<LocationWatch>;
    };
    /**
     * 모바일 전용 푸시 API
     *
     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
     */
    push: {
        /**
         * 네이티브 디바이스 푸시 토큰 조회.
         * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
         */
        getToken: () => Promise<{
            token: string;
            platform?: string;
        } | null>;
        /** 알림 권한 요청 (웹은 Web Notification 권한) */
        requestPermission: () => Promise<boolean>;
        /** 로컬 알림 예약 (패키징 앱 전용) */
        scheduleLocal: (options: LocalNotificationOptions) => Promise<string | null>;
        /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
        setBadgeCount: (count: number) => Promise<boolean>;
    };
    /**
     * 크로스 플랫폼 알림 API
     */
    notification: {
        /**
         * 알림 표시
         */
        show: (options: NotificationOptions) => Promise<boolean>;
        /**
         * 알림 권한 요청
         */
        requestPermission: () => Promise<boolean>;
    };
    /**
     * 크로스 플랫폼 셸 API
     */
    shell: {
        /**
         * 외부 URL 열기
         */
        openExternal: (url: string) => Promise<boolean>;
    };
    /**
     * 데스크톱 전용 창 제어 API
     */
    window: {
        minimize: () => Promise<void>;
        maximize: () => Promise<void>;
        unmaximize: () => Promise<void>;
        close: () => Promise<void>;
        isMaximized: () => Promise<boolean>;
        setTitle: (title: string) => Promise<void>;
        setFullScreen: (flag: boolean) => Promise<void>;
    };
    /**
     * 데스크톱 전용 시스템 정보 API
     */
    system: {
        getInfo: () => Promise<SystemInfo | null>;
        getMemory: () => Promise<MemoryInfo | null>;
    };
    /**
     * 모바일 전용 생체인증 API
     */
    biometric: {
        isAvailable: () => Promise<BiometricInfo | null>;
        authenticate: (options?: BiometricOptions) => Promise<BiometricResult | null>;
    };
    /**
     * 모바일 전용 보안 저장소 API
     */
    secureStore: {
        setItem: (key: string, value: string) => Promise<boolean>;
        getItem: (key: string) => Promise<string | null>;
        deleteItem: (key: string) => Promise<boolean>;
    };
    /**
     * 모바일 전용 AdMob API
     */
    admob: {
        showInterstitial: () => Promise<boolean>;
        showRewarded: () => Promise<boolean>;
    };
    /**
     * 크로스 플랫폼 음성 인식(STT) API
     *
     * - 모바일(패키징 앱): 네이티브 STT 브릿지(expo-speech-recognition — iOS SFSpeechRecognizer / Android SpeechRecognizer)
     * - 웹/데스크톱: Web Speech API(webkitSpeechRecognition)
     *
     * iOS WKWebView 는 Web Speech API 를 지원하지 않으므로, 패키징 앱에서는 speech 네이티브 기능을 켜면
     * 자동으로 네이티브 브릿지 경로를 사용한다.
     *
     * @example
     * ```typescript
     * if (await cb.native.speech.isAvailable()) {
     *   const result = await cb.native.speech.recognize({
     *     lang: 'ko-KR',
     *     onPartial: (text) => console.log('부분 결과:', text),
     *   })
     *   console.log('최종:', result.transcript)
     * }
     * ```
     */
    speech: {
        /**
         * 음성 인식 지원 여부
         */
        isAvailable: () => Promise<boolean>;
        /**
         * 음성 인식 시작 → 최종 transcript 반환.
         * `options.onPartial` 로 중간 결과를 실시간 수신할 수 있다.
         */
        recognize: (options?: SpeechRecognizeOptions) => Promise<SpeechResult>;
        /**
         * 진행 중인 음성 인식 중지
         */
        stop: () => Promise<void>;
    };
}

/**
 * OAuth 프로바이더 타입
 */
type OAuthProvider = "google" | "kakao" | "naver" | "apple" | "github" | "discord";
/**
 * 활성화된 OAuth 프로바이더 정보
 */
interface EnabledProviderInfo {
    provider: OAuthProvider;
    client_id: string;
}
/**
 * 활성화된 프로바이더 목록 응답
 */
interface EnabledProvidersResponse {
    providers: EnabledProviderInfo[];
}
/**
 * OAuth 인증 URL 응답
 */
interface GetAuthorizationURLResponse {
    authorization_url: string;
}
/**
 * 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;
}

/**
 * 3rd-party 인앱 브라우저(카카오톡, 라인, 인스타그램, 페이스북 등) 감지
 * 구글은 이런 환경에서 OAuth를 차단(disallowed_useragent)하므로 별도 처리 필요
 */
declare function detectInAppBrowser(): {
    type: "kakaotalk" | "line" | "instagram" | "facebook" | "naverapp" | "wechat" | "other";
    ua: string;
} | null;
/**
 * 3rd-party 인앱 브라우저에서 현재 URL을 외부(시스템) 브라우저로 강제로 여는 방법 제공
 * - 카카오톡: kakaotalk://web/openExternal?url=...
 * - 라인: line://nv/openURL?url=...
 * - 그 외: 사용자에게 안내 메시지 표시 권장
 */
declare function escapeToExternalBrowser(currentUrl?: string): boolean;
/**
 * OAuth API
 * 소셜 로그인 (Google, Naver, GitHub, Discord)
 */
declare class OAuthAPI {
    private http;
    /**
     * 부팅 안전망(consumeRedirectCallbackOnBoot)이 리다이렉트 콜백을 자동 소비했을 때의 promise.
     * 앱이 그 후 `getCallbackResult()` 를 호출해도 중복으로 `bootstrapRefreshCookie` 를
     * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
     */
    private bootConsumePromise;
    constructor(http: HttpClient);
    /**
     * 활성화된 OAuth 프로바이더 목록 조회
     * 콘솔에서 설정된 소셜 로그인 프로바이더 목록을 반환합니다.
     *
     * @example
     * ```typescript
     * const { providers } = await cb.oauth.getEnabledProviders()
     * // [{ provider: 'google', client_id: '...' }, { provider: 'kakao', client_id: '...' }]
     * ```
     */
    getEnabledProviders(): Promise<EnabledProvidersResponse>;
    /**
     * 소셜 로그인 (리다이렉트 방식) - 권장
     *
     * 기존 회원만 로그인 (`intent=signin` 명시). 이 앱에서 처음인 사용자는 콜백에서
     * `error=account_not_found` 를 받아 가입 안내 UX 로 분기해야 한다. 신규 가입까지 한 번에
     * 처리하려면 [signUp] 을 사용한다.
     *
     * 기본적으로 미가입 사용자는 콜백에서 `error=account_not_found` 로 돌아온다(신규 자동가입 안 됨).
     * 로그인/가입을 한 버튼으로 처리하려면 `{ createIfNotExists: true }` 를 주거나, 별도 "회원가입"
     * 버튼에서 [signUp] 을 호출한다.
     *
     * @param provider - OAuth 프로바이더 (google, naver, github, discord)
     * @param callbackUrl - OAuth 완료 후 리다이렉트될 앱의 URL
     * @param state - 선택적 state 파라미터 (CSRF 방지 등)
     * @param options - `createIfNotExists: true` 면 미가입 사용자를 자동 가입시킨다([signUp] 과 동일 동작).
     *
     * @example
     * ```typescript
     * // "로그인" 버튼 — 기존 회원만. 신규는 account_not_found.
     * await cb.oauth.signIn('google', 'https://myapp.com/oauth/callback')
     *
     * // 로그인=가입 통합 버튼 — 신규면 자동 가입
     * await cb.oauth.signIn('google', 'https://myapp.com/oauth/callback', undefined, { createIfNotExists: true })
     * ```
     *
     * @example
     * ```typescript
     * // callback 페이지에서 — 미가입이면 가입 화면으로 안내
     * const result = await cb.oauth.getCallbackResult()
     * if (result?.error === 'account_not_found') {
     *     window.location.href = '/signup'
     * }
     * ```
     */
    signIn(provider: OAuthProvider, callbackUrl: string, state?: string, options?: {
        createIfNotExists?: boolean;
    }): Promise<void>;
    /**
     * 소셜 회원가입 (리다이렉트 방식) — 사용자가 명시적으로 가입 의사를 표시한 경우에만 호출.
     *
     * 기존 회원이면 그대로 로그인 (idempotent). 없으면 신규 AppMember 생성.
     * "로그인" 버튼에는 [signIn] 을 쓰고, "회원가입" 버튼에서만 이 메서드를 호출해야 silent
     * auto-signup 회귀를 방지할 수 있다.
     */
    signUp(provider: OAuthProvider, callbackUrl: string, state?: string): Promise<void>;
    private startCentralOAuth;
    /**
     * 소셜 로그인 (팝업 방식)
     * 팝업 창에서 소셜 로그인을 처리하고 결과를 Promise로 반환합니다.
     * Google Cloud Console에 별도 등록 불필요.
     * 콜백 페이지가 자동으로 제공되므로 callbackUrl은 선택사항입니다.
     *
     * ⚠️ 일부 배포 환경에서 COOP(Cross-Origin-Opener-Policy) 정책으로 인해
     * 팝업 닫힘 감지가 제한될 수 있습니다. 3분 타임아웃이 적용되며,
     * 안정적인 동작이 필요하면 signIn() (리다이렉트 방식)을 사용하세요.
     *
     * @param provider - OAuth 프로바이더
     * @param callbackUrl - (선택) OAuth 완료 후 리다이렉트될 팝업의 URL. 미지정 시 서버 제공 콜백 사용.
     * @returns 로그인 결과
     *
     * @example
     * ```typescript
     * // 간단 사용 (콜백 페이지 불필요)
     * const result = await cb.oauth.signInWithPopup('google')
     * console.log('로그인 성공:', result.member_id)
     *
     * // 커스텀 콜백 URL 사용 (기존 방식)
     * const result = await cb.oauth.signInWithPopup('google', 'https://myapp.com/oauth/callback')
     * ```
     */
    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 = await cb.oauth.getCallbackResult()
     * if (result) {
     *     if (result.error) {
     *         alert('로그인 실패: ' + result.error)
     *     } else {
     *         window.location.href = '/'
     *     }
     * }
     * ```
     */
    getCallbackResult(): Promise<{
        access_token?: string;
        refresh_token?: string;
        member_id?: string;
        is_new_member?: boolean;
        email?: string;
        state?: string;
        error?: string;
    } | null>;
    /**
     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
     *
     * OAuth 리다이렉트 콜백 페이지에서 앱이 `getCallbackResult()` 를 호출하지 않아도,
     * `new ConnectBase()` 만으로 URL 의 토큰(`?access_token=&refresh_token=&member_id=`)을
     * 적재해 세션을 확립한다.
     *
     * **왜 필요한가:** 정적 호스팅(웹 스토리지)은 SPA fallback 으로 `/auth/callback` 같은 콜백
     * 경로에 홈 `index.html` 을 서빙한다. 그 페이지가 콜백을 처리하지 않으면 URL 토큰이 영영
     * 소비되지 않아 "로그인 → 다시 로그인 페이지" 무한 루프가 발생한다 (여러 사용자 동시 보고).
     * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
     *
     * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
     *
     * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
     */
    consumeRedirectCallbackOnBoot(): Promise<boolean>;
    private doConsumeRedirectOnBoot;
    /**
     * 콜백 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" | "payapp" | "paypal" | "paddle" | "dodo";
/**
 * 자격증명 모드 — 콘솔에 등록한 테스트 키/라이브 키 중 어느 쪽으로 결제할지.
 * 프로바이더별 기본 모드는 콘솔에서 정한다.
 */
type PaymentMode = "test" | "live";
type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" | "partial_canceled" | "aborted" | "expired" | "failed";
interface PreparePaymentRequest {
    payment_provider?: PaymentProvider;
    /**
     * 사용할 자격증명 모드 오버라이드(선택).
     *
     * **서버에서 시크릿 키(`cb_sk_*`)로 호출할 때만 적용된다.** 브라우저에 실리는 공개 키
     * (`cb_pk_*`) 호출에서는 무시된다 — 클라이언트가 test 를 골라 실제 돈 없이 "결제 성공"을
     * 만들 수 있으면 결제 성공에 걸린 권한 부여가 통째로 우회되기 때문이다.
     *
     * 모드 결정 우선순위: 이 오버라이드 → **퍼블릭 키에 고정된 모드**(콘솔에서 키마다 지정) →
     * 콘솔의 프로바이더 모드 → test. 브라우저 앱에서 QA/프로덕션 결제를 나누려면 이 필드가 아니라
     * 키 단위 `payment_mode` 를 쓴다(`cb.publicKey` 참조).
     */
    payment_mode?: PaymentMode;
    /**
     * MoR 단건결제용 price/product ref 오버라이드(선택).
     *
     * Dodo 처럼 checkout 이 카탈로그 상품만 참조하는 프로바이더는 임의 금액 청구에
     * pay-what-you-want 상품이 필요하다. 보통 콘솔에 저장한 기본값을 쓰므로 생략하면 되고,
     * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
     */
    provider_price_ref?: string;
    amount: number;
    order_name: string;
    order_id?: string;
    customer_email?: string;
    customer_name?: string;
    customer_phone?: string;
    metadata?: Record<string, unknown>;
}
interface PreparePaymentResponse {
    payment_id: string;
    order_id: string;
    amount: number;
    order_name: string;
    payment_provider: PaymentProvider;
    /** 이 결제가 사용한 자격증명 모드. */
    payment_mode: PaymentMode;
    customer_key: string;
    toss_client_key: string;
    success_url: string;
    fail_url: string;
    stripe_client_secret?: string;
    stripe_publishable_key?: string;
    payapp_pay_url?: string;
    payapp_mul_no?: string;
    paypal_approve_url?: string;
    paypal_order_id?: string;
    provider_ref?: string;
    client_token?: string;
    environment?: string;
    checkout_url?: string;
    launch_mode?: "overlay" | "redirect";
}
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;
    amount: number;
    stripe_payment_intent_id?: string;
    paypal_order_id?: string;
    provider_ref?: string;
}
interface ConfirmPaymentResponse {
    payment_id: string;
    order_id: string;
    amount: number;
    status: PaymentStatus;
    method: string;
    receipt_url?: string;
    approved_at?: string;
}
interface CancelPaymentRequest {
    cancel_reason: string;
    cancel_amount?: number;
}
interface CancelPaymentResponse {
    payment_id: string;
    order_id: string;
    original_amount: number;
    canceled_amount: number;
    status: PaymentStatus;
    canceled_at?: string;
}
interface PaymentDetail {
    payment_id: string;
    order_id: string;
    order_name: string;
    /** 고객이 실제 청구받은 금액 — `currency` 기준 최소단위 */
    amount: number;
    /** `amount` 의 통화 (ISO 4217) */
    currency: string;
    /**
     * 정산통화 환산액 (MoR 프로바이더가 제공할 때만).
     *
     * Paddle/Dodo 는 고객에게 표시통화로 청구하고 머천트에게는 환산된 정산통화로 지급한다.
     * 실제 입금액 대사에 쓰고, **고객에게 보여줄 금액은 언제나 `amount`/`currency`** 다.
     */
    settlement_amount?: number;
    /** `settlement_amount` 의 통화 (ISO 4217) */
    settlement_currency?: string;
    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
    country?: string;
    status: PaymentStatus;
    payment_provider?: PaymentProvider;
    /** 이 결제가 사용한 자격증명 모드 (test | live). */
    payment_mode?: PaymentMode;
    method?: string;
    customer_id?: string;
    customer_email?: string;
    customer_name?: string;
    receipt_url?: string;
    approved_at?: string;
    canceled_at?: string;
    canceled_amount?: number;
    cancel_reason?: string;
    failure_code?: string;
    failure_message?: string;
    metadata?: Record<string, unknown>;
    created_at: string;
    updated_at: string;
}
/** `cb.payment.list` 필터 옵션. 모두 선택. 백엔드 `ListPaymentsRequest` 쿼리에 매핑. */
interface ListPaymentsOptions {
    /** pending | done | canceled | failed */
    status?: string;
    /** test | live. 미지정 시 전체. 테스트 결제를 걸러 실매출만 보려면 "live". */
    mode?: PaymentMode;
    /** ISO8601(RFC3339) 시작일 필터. */
    startDate?: string;
    /** ISO8601(RFC3339) 종료일 필터. */
    endDate?: string;
    /** 기본 50. */
    limit?: number;
    offset?: number;
}
/** 결제 목록 항목. 백엔드 `PaymentListItem` 매핑. */
interface PaymentListItem {
    payment_id: string;
    order_id: string;
    order_name: string;
    /** 고객이 실제 청구받은 금액 — `currency` 기준 최소단위 */
    amount: number;
    /** `amount` 의 통화 (ISO 4217). 다통화 결제에서 앱 기본 통화를 가정하면 거짓 금액이 된다 */
    currency: string;
    status: PaymentStatus;
    method?: string;
    /** toss | stripe 등 */
    payment_provider: string;
    customer_name?: string;
    customer_email?: string;
    approved_at?: string;
    created_at: string;
}
/** `cb.payment.list` 반환값. 백엔드 `ListPaymentsResponse` 매핑. */
interface PaymentListResult {
    payments: PaymentListItem[];
    total: number;
    limit: number;
    offset: number;
}

declare class PaymentAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * 결제 준비
     * 토스 결제 위젯에 필요한 정보를 반환합니다.
     *
     * @param data - 결제 준비 정보 (금액, 상품명, 고객 정보 등)
     * @returns 토스 클라이언트 키, 고객 키, 성공/실패 URL 등
     *
     * @example
     * ```typescript
     * const result = await cb.payment.prepare({
     *     amount: 10000,
     *     order_name: '프리미엄 1개월',
     *     customer_email: 'test@example.com',
     *     customer_name: '홍길동'
     * })
     *
     * // 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 결제 플로우
     * 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' })
     * }
     *
     * // PayApp 결제 플로우 (위젯 불필요 — 호스팅 결제창으로 redirect)
     * // 결제 결과는 서버의 feedbackurl webhook 으로 확정되며, 사용자는 success_url 로 복귀한다.
     * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
     *   window.location.href = result.payapp_pay_url
     * }
     * ```
     *
     * @remarks
     * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
     */
    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>;
    /**
     * 결제 승인
     * 토스에서 결제 완료 후 콜백으로 받은 정보로 결제를 최종 승인합니다.
     *
     * @param data - 결제 승인 정보 (paymentKey, orderId, amount)
     * @returns 승인된 결제 정보
     *
     * @example
     * ```typescript
     * // 토스 결제 성공 콜백에서 호출
     * const result = await client.payment.confirm({
     *     payment_key: 'tgen_20230101000000...',
     *     order_id: 'order_123',
     *     amount: 10000
     * })
     *
     * if (result.status === 'done') {
     *     console.log('결제 완료!')
     * }
     * ```
     */
    confirm(data: ConfirmPaymentRequest): Promise<ConfirmPaymentResponse>;
    /**
     * 결제 취소
     * 완료된 결제를 취소합니다. 부분 취소도 가능합니다.
     *
     * @param paymentId - 결제 ID (Connect Base에서 발급한 ID)
     * @param data - 취소 정보 (사유, 부분 취소 금액)
     * @returns 취소된 결제 정보
     *
     * @example
     * ```typescript
     * // 전액 취소
     * const result = await client.payment.cancel(paymentId, {
     *     cancel_reason: '고객 요청'
     * })
     *
     * // 부분 취소
     * const result = await client.payment.cancel(paymentId, {
     *     cancel_reason: '부분 환불',
     *     cancel_amount: 5000
     * })
     * ```
     */
    cancel(paymentId: string, data: CancelPaymentRequest): Promise<CancelPaymentResponse>;
    /**
     * 주문 ID로 결제 조회
     * 특정 주문의 결제 상태를 조회합니다.
     *
     * @param orderId - 주문 ID
     * @returns 결제 상세 정보
     *
     * @example
     * ```typescript
     * const payment = await client.payment.getByOrderId('order_123')
     * console.log(`결제 상태: ${payment.status}`)
     * console.log(`결제 금액: ${payment.amount}원`)
     * ```
     */
    getByOrderId(orderId: string): Promise<PaymentDetail>;
    /**
     * 앱의 결제 내역 목록을 조회한다 (필터/페이지네이션 지원).
     *
     * 서버사이드 전용 — service_role(ctx.cbAdmin, management_scopes=["payment:read"]) 또는 콘솔 JWT
     * 인증이 필요하다. 재무 데이터이므로 Public Key(cb_pk_) 단독 브라우저 SDK 인스턴스로는 호출할 수
     * 없다. (다른 payment 메서드와 달리 /v1/public 이 아니라 앱 스코프 dual-auth 라우트를 쓴다.)
     *
     * @example
     * ```typescript
     * // 함수(service_role, management_scopes: ["payment:read"]) 안에서
     * const { payments, total } = await ctx.cbAdmin.payment.list(ctx.appId, { status: 'done', limit: 20 })
     * ```
     */
    list(appId: string, options?: ListPaymentsOptions): Promise<PaymentListResult>;
}

/**
 * Public Key 관련 타입 정의
 */
/**
 * 이 키로 들어온 결제가 쓸 자격증명 모드.
 *
 * - `inherit`(기본): 앱 결제 설정의 프로바이더 모드를 따른다.
 * - `test`: 이 키의 결제는 항상 테스트 키로 처리된다.
 * - `live`: 이 키의 결제는 항상 라이브 키로 처리된다.
 *
 * 앱 하나로 QA 빌드와 프로덕션 빌드를 함께 운영할 때 쓴다 — QA 빌드에 `test` 키를 심으면
 * 앱 설정이 라이브여도 그 키의 결제만 테스트로 처리되므로, 라이브 전환 이후에도 안전하게
 * 결제 회귀 테스트를 할 수 있다.
 *
 * 모드를 정하는 주체가 **서버에 저장된 키 설정**이라 클라이언트는 고를 수 없다. QA 키가
 * 유출돼도 만들 수 있는 건 테스트 결제뿐이다(권한 지급 로직이 결제의 `payment_mode` 를 함께
 * 검사하도록 만드는 것을 권장한다).
 */
type PublicKeyPaymentMode = "inherit" | "test" | "live";
/**
 * Public Key 아이템
 */
interface PublicKeyItem {
    /** Public Key ID */
    id: string;
    /** Public Key 이름 */
    name: string;
    /** 키 앞 12자리 (표시용) */
    key_prefix: string;
    /** 활성화 상태 */
    is_active: boolean;
    /** 이 키로 들어온 결제의 자격증명 모드 */
    payment_mode: PublicKeyPaymentMode;
    /** 마지막 사용 시간 */
    last_used_at?: string;
    /** 만료일 (null이면 무제한) */
    expires_at?: string;
    /** 생성일 */
    created_at: string;
}
/**
 * Public Key 생성 요청
 */
interface CreatePublicKeyRequest {
    /** Public Key 이름 (예: Production, Development) */
    name: string;
    /** 이 키로 들어온 결제의 자격증명 모드 (기본: inherit) */
    payment_mode?: PublicKeyPaymentMode;
    /** 만료일 (옵션) */
    expires_at?: string;
}
/**
 * Public Key 생성 응답 (전체 키는 이때만 반환됨)
 */
interface CreatePublicKeyResponse {
    /** Public Key ID */
    id: string;
    /** Public Key 이름 */
    name: string;
    /** 전체 키 값 (생성 시에만 반환, 안전하게 보관 필요) */
    key: string;
    /** 키 앞 12자리 (표시용) */
    key_prefix: string;
    /** 활성화 상태 */
    is_active: boolean;
    /** 이 키로 들어온 결제의 자격증명 모드 */
    payment_mode: PublicKeyPaymentMode;
    /** 만료일 */
    expires_at?: string;
    /** 생성일 */
    created_at: string;
}
/**
 * Public Key 목록 조회 응답
 */
interface FetchPublicKeysResponse {
    public_keys: PublicKeyItem[];
}
/**
 * Public Key 수정 요청
 */
interface UpdatePublicKeyRequest {
    /** Public Key 이름 변경 */
    name?: string;
    /** 활성화/비활성화 */
    is_active?: boolean;
    /** 이 키로 들어온 결제의 자격증명 모드 변경 */
    payment_mode?: PublicKeyPaymentMode;
}
/**
 * Public Key 수정 응답
 */
interface UpdatePublicKeyResponse {
    id: string;
    name: string;
    key_prefix: string;
    is_active: boolean;
    payment_mode: PublicKeyPaymentMode;
    expires_at?: string;
    created_at: string;
}

/**
 * Public Key 관리 API
 *
 * 콘솔 JWT 또는 **service_role 함수**(`ctx.cbAdmin`)로 호출한다. 브라우저에서 Public Key(cb_pk_)
 * 단독으로는 호출할 수 없다 — 키가 자기 자신을 발급/수정하는 경로를 막는다.
 *
 * service_role 함수에서 쓰려면 함수 `management_scopes` 에 스코프를 opt-in 해야 한다:
 * `publickey:read`(목록 조회) / `publickey:manage`(생성·수정·삭제).
 *
 * `payment_mode` 로 키마다 결제 자격증명 모드를 고정할 수 있다 — QA 빌드에 `test` 키를 심으면
 * 앱 설정과 무관하게 그 키의 결제만 테스트로 처리된다(platform-issue 019f9961).
 *
 * @example
 * ```typescript
 * // Public Key 목록 조회
 * const keys = await cb.publicKey.getPublicKeys('app-id')
 *
 * // QA 빌드용 테스트 결제 키 생성
 * const newKey = await cb.publicKey.createPublicKey('app-id', {
 *   name: 'QA',
 *   payment_mode: 'test',
 * })
 * console.log(newKey.key)          // 전체 키 (이때만 볼 수 있음!)
 * console.log(newKey.payment_mode) // 'test' — 되읽어 검증
 *
 * // 모드 변경 / 비활성화
 * await cb.publicKey.updatePublicKey('app-id', 'key-id', { payment_mode: 'live' })
 * await cb.publicKey.updatePublicKey('app-id', 'key-id', { is_active: false })
 *
 * // Public Key 삭제
 * await cb.publicKey.deletePublicKey('app-id', 'key-id')
 * ```
 */
declare class PublicKeyAPI {
    private http;
    constructor(http: HttpClient);
    private ensureServerAuth;
    /**
     * 앱의 Public Key 목록을 조회합니다 (management_scope: `publickey:read`)
     * @param appId 앱 ID
     */
    getPublicKeys(appId: string): Promise<FetchPublicKeysResponse>;
    /**
     * 새 Public Key 를 생성합니다
     *
     * **중요**: 반환되는 `key` 값은 이 응답에서만 볼 수 있습니다.
     * 안전한 곳에 저장하세요.
     *
     * @param appId 앱 ID
     * @param data 생성할 Public Key 정보 (`payment_mode` 로 결제 모드 고정 가능)
     *
     * (management_scope: `publickey:manage`)
     */
    createPublicKey(appId: string, data: CreatePublicKeyRequest): Promise<CreatePublicKeyResponse>;
    /**
     * Public Key 를 수정합니다 (이름 변경, 활성화/비활성화, `payment_mode` 변경)
     *
     * (management_scope: `publickey:manage`)
     * @param appId 앱 ID
     * @param keyId Public Key ID
     * @param data 수정할 정보
     */
    updatePublicKey(appId: string, keyId: string, data: UpdatePublicKeyRequest): Promise<UpdatePublicKeyResponse>;
    /**
     * Public Key 를 삭제합니다 (management_scope: `publickey:manage`)
     * @param appId 앱 ID
     * @param keyId Public Key ID
     */
    deletePublicKey(appId: string, keyId: string): Promise<void>;
}

/**
 * Push Notification Types
 */
type PushPlatform = "ios" | "android" | "web";
interface RegisterDeviceRequest {
    /** 디바이스 토큰 (APNS/FCM/Web Push) */
    device_token: string;
    /** 플랫폼 */
    platform: PushPlatform;
    /** 디바이스 고유 ID (optional) */
    device_id?: string;
    /** 디바이스 이름 (예: "iPhone 15 Pro") */
    device_name?: string;
    /** 디바이스 모델 (예: "iPhone15,2") */
    device_model?: string;
    /** OS 버전 (예: "17.0") */
    os_version?: string;
    /** 앱 버전 (예: "1.0.0") */
    app_version?: string;
    /** 언어 코드 (예: "ko") */
    language?: string;
    /** 타임존 (예: "Asia/Seoul") */
    timezone?: string;
}
interface DeviceInfo {
    id: string;
    device_token: string;
    platform: PushPlatform;
    device_id?: string;
    device_name?: string;
    device_model?: string;
    os_version?: string;
    app_version?: string;
    language?: string;
    timezone?: string;
    is_active: boolean;
    last_active_at?: string;
    created_at: string;
    updated_at: string;
}
interface SubscribeTopicRequest {
    /** 토픽 이름 */
    topic_name: string;
}
interface VAPIDPublicKeyResponse {
    public_key: string;
}
interface WebPushSubscription {
    endpoint: string;
    expirationTime?: number | null;
    keys: {
        p256dh: string;
        auth: string;
    };
}

/**
 * `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;
}
/**
 * `cb.push.sendToTopic` 페이로드. 백엔드 `dto.SendPushToTopicRequest` 에 매핑되며,
 * topic_name 은 메서드 인자로 받아 SDK 가 채운다. (members 발송과 달리 대상은 토픽 구독자 전체)
 */
interface SendToTopicPayload {
    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;
}
/**
 * 푸시 통계. 백엔드 `dto.PushStatsResponse` 와 1:1 매핑. `cb.push.getStats` 반환값.
 * open_rate / click_rate 는 % 단위. 서버사이드(ctx.cbAdmin) 전용 — Public Key 단독 SDK 는 호출 불가.
 */
interface PushStatsResult {
    total_devices: number;
    active_devices: number;
    ios_devices: number;
    android_devices: number;
    web_devices: number;
    total_messages: number;
    sent_messages: number;
    failed_messages: number;
    pending_messages: number;
    total_topics: number;
    total_sent: number;
    total_opened: number;
    total_clicked: number;
    /** 열람율 (%) */
    open_rate: number;
    /** 클릭율 (%) */
    click_rate: number;
}
/**
 * 푸시 알림 API
 *
 * @example
 * ```typescript
 * // 디바이스 등록 (모바일 앱)
 * const device = await cb.push.registerDevice({
 *     device_token: 'fcm-token-here',
 *     platform: 'android',
 *     device_name: 'Galaxy S24',
 * })
 *
 * // 토픽 구독 (device_token 필수)
 * await cb.push.subscribeTopic(device.device_token, 'announcements')
 *
 * // Web Push 등록 (브라우저)
 * const vapidKey = await cb.push.getVAPIDPublicKey()
 * const subscription = await registration.pushManager.subscribe({
 *     userVisibleOnly: true,
 *     applicationServerKey: vapidKey.public_key
 * })
 * await cb.push.registerWebPush(subscription)
 * ```
 */
declare class PushAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * 디바이스 등록 (APNS/FCM 토큰)
     *
     * @param request 디바이스 등록 정보
     * @returns 등록된 디바이스 정보
     *
     * @example
     * ```typescript
     * // iOS 디바이스 등록
     * const device = await cb.push.registerDevice({
     *     device_token: 'apns-token-here',
     *     platform: 'ios',
     *     device_name: 'iPhone 15 Pro',
     *     device_model: 'iPhone15,2',
     *     os_version: '17.0',
     *     app_version: '1.0.0',
     * })
     *
     * // Android 디바이스 등록
     * const device = await cb.push.registerDevice({
     *     device_token: 'fcm-token-here',
     *     platform: 'android',
     *     device_name: 'Galaxy S24',
     * })
     * ```
     */
    registerDevice(request: RegisterDeviceRequest): Promise<DeviceInfo>;
    /**
     * 디바이스 등록 해제
     *
     * @param deviceToken 디바이스 토큰
     *
     * @example
     * ```typescript
     * await cb.push.unregisterDevice('fcm-token-here')
     * ```
     */
    unregisterDevice(deviceToken: string): Promise<void>;
    /**
     * 토픽 구독
     *
     * @param deviceToken 디바이스 토큰
     * @param topicName 토픽 이름
     *
     * @example
     * ```typescript
     * await cb.push.subscribeTopic('fcm-token-here', 'announcements')
     * ```
     */
    subscribeTopic(deviceToken: string, topicName: string): Promise<void>;
    /**
     * 토픽 구독 해제
     *
     * @param deviceToken 디바이스 토큰
     * @param topicName 토픽 이름
     *
     * @example
     * ```typescript
     * await cb.push.unsubscribeTopic('fcm-token-here', 'marketing')
     * ```
     */
    unsubscribeTopic(deviceToken: string, topicName: string): Promise<void>;
    /**
     * VAPID Public Key 조회 (Web Push용)
     *
     * @returns VAPID Public Key
     *
     * @example
     * ```typescript
     * const vapidKey = await cb.push.getVAPIDPublicKey()
     *
     * // Service Worker에서 Push 구독
     * const registration = await navigator.serviceWorker.ready
     * const subscription = await registration.pushManager.subscribe({
     *     userVisibleOnly: true,
     *     applicationServerKey: urlBase64ToUint8Array(vapidKey.public_key)
     * })
     *
     * // 구독 정보 등록
     * await cb.push.registerWebPush(subscription)
     * ```
     */
    getVAPIDPublicKey(): Promise<VAPIDPublicKeyResponse>;
    /**
     * Web Push 구독 등록
     *
     * @param subscription PushSubscription 객체 또는 WebPushSubscription
     *
     * @example
     * ```typescript
     * // 브라우저에서 Push 구독 후 등록
     * const registration = await navigator.serviceWorker.ready
     * const subscription = await registration.pushManager.subscribe({
     *     userVisibleOnly: true,
     *     applicationServerKey: vapidPublicKey
     * })
     *
     * await cb.push.registerWebPush(subscription)
     * ```
     */
    registerWebPush(subscription: PushSubscription | WebPushSubscription): Promise<DeviceInfo>;
    /**
     * Web Push 구독 해제
     *
     * @param deviceToken Web Push endpoint URL (등록 시 사용한 endpoint)
     */
    unregisterWebPush(deviceToken: string): Promise<void>;
    /**
     * 회원 ID 목록으로 푸시 발송 — Functions / 서버사이드 인증 환경 전용.
     *
     * 백엔드 라우트 `POST /v1/apps/:appID/push/send` 는 콘솔 JWT, User Secret Key(`cb_sk_`),
     * 또는 service_role 토큰(`ctx.cbAdmin`)을 받는다. 브라우저 SDK 의 Public Key(`cb_pk_`)
     * **단독** 인스턴스에서는 호출 자체가 차단되며(권한 누설 방지), 명확한 에러를 던진다.
     * 위임 Bearer 토큰을 가진 인스턴스(`ctx.cbAdmin`/`ctx.cb`)는 cb_pk_ 가 앱 식별용으로만
     * 실리므로 허용된다.
     *
     * @param appId 발송 대상 앱 ID.
     * @param memberIds 받는 회원 ID 배열 (UUID).
     * @param payload 푸시 내용/옵션.
     *
     * @example
     * ```ts
     * // ConnectBase Function (service_role=true) — 시크릿 키 없이 ctx.cbAdmin 으로 발송
     * const result = await ctx.cbAdmin.push.sendToMembers(ctx.appId, [memberId], {
     *     title: '새 알림',
     *     body: '확인해보세요',
     *     data: { route: '/notifications' },
     * })
     * console.log(result.message_id, result.sent_count)
     * ```
     */
    sendToMembers(appId: string, memberIds: string[], payload: SendToMembersPayload): Promise<SendPushResult>;
    /**
     * 토픽 구독자 전체에게 푸시 알림을 발송한다 (서버 사이드 전용).
     *
     * 백엔드 라우트 `POST /v1/apps/:appID/push/send-to-topic` 는 콘솔 JWT, User Secret Key(`cb_sk_`),
     * 또는 service_role 토큰(`ctx.cbAdmin`)을 받는다. `sendToMembers` 와 동일하게 브라우저 SDK 의
     * Public Key(`cb_pk_`) **단독** 인스턴스에서는 호출이 차단되며, 위임 Bearer 토큰을 가진
     * 인스턴스(`ctx.cbAdmin`/`ctx.cb`)는 cb_pk_ 가 앱 식별용으로만 실리므로 허용된다.
     *
     * 정기 알림(일일 리마인더 등)을 ConnectBase Function 스케줄러에서 `ctx.cbAdmin` 으로 발송하는
     * 것이 대표 유스케이스다 — 시크릿 키를 콘솔에서 별도로 발급해 함수 secret 에 넣을 필요가 없다.
     *
     * @param appId 발송 대상 앱 ID.
     * @param topicName 발송 대상 토픽 이름 (예: 'daily-0900').
     * @param payload 푸시 내용/옵션.
     *
     * @example
     * ```ts
     * // ConnectBase Function (service_role=true) — 시크릿 키 없이 ctx.cbAdmin 으로 토픽 발송
     * const result = await ctx.cbAdmin.push.sendToTopic(ctx.appId, 'daily-0900', {
     *     title: '오늘의 학습 리마인더',
     *     body: '잊지 말고 학습을 이어가세요!',
     *     data: { route: '/today' },
     * })
     * console.log(result.message_id, result.sent_count)
     * ```
     */
    sendToTopic(appId: string, topicName: string, payload: SendToTopicPayload): Promise<SendPushResult>;
    /**
     * 앱의 푸시 통계(도달/오픈율/클릭율, 디바이스/메시지/토픽 수)를 조회한다.
     *
     * 서버사이드 전용 — service_role(ctx.cbAdmin, management_scopes=["push:read"]) 또는 콘솔 JWT
     * 인증이 필요하다. sendToMembers/sendToTopic 과 동일한 위임 가드 — cb_pk_ 단독(브라우저) SDK
     * 인스턴스는 차단하고, 위임 Bearer(ctx.cbAdmin) 인스턴스는 허용한다.
     *
     * @example
     * ```typescript
     * // 함수(service_role, management_scopes: ["push:read"]) 안에서
     * const stats = await ctx.cbAdmin.push.getStats(ctx.appId)
     * console.log(stats.open_rate, stats.click_rate)
     * ```
     */
    getStats(appId: string): Promise<PushStatsResult>;
    /**
     * 브라우저 고유 ID 생성 (localStorage에 저장)
     */
    private generateDeviceId;
    /**
     * 브라우저 이름 감지
     */
    private getBrowserName;
    /**
     * OS 정보 감지
     */
    private getOSInfo;
}

interface PublishMessageRequest {
    body: unknown;
    headers?: Record<string, string>;
    delay_seconds?: number;
    deduplication_id?: string;
    ttl_seconds?: number;
}
interface PublishMessageResponse {
    message_id: string;
    published_at: string;
}
interface PublishBatchRequest {
    messages: PublishMessageRequest[];
}
interface PublishBatchResponse {
    published: PublishMessageResponse[];
    failed: number;
    total: number;
}
interface ConsumeOptions {
    max_messages?: number;
    visibility_timeout?: number;
    /** false(기본값): 명시적 Ack 필요 (at-least-once). true: 즉시 자동 Ack (at-most-once) */
    auto_ack?: boolean;
}
interface QueueMessage {
    message_id: string;
    body: unknown;
    headers?: Record<string, string>;
    published_at: string;
    delivery_count: number;
    queue_name: string;
}
interface ConsumeMessagesResponse {
    messages: QueueMessage[];
    /** auto_ack=false 시 반환. Ack 호출 시 사용 */
    ack_token?: string;
}
interface AckMessagesRequest {
    message_ids: string[];
    /** auto_ack=false 소비 시 반환된 ack_token */
    ack_token?: string;
}
interface NackMessageRequest {
    payload: unknown;
    delay_seconds?: number;
}
interface QueueInfoResponse {
    id: string;
    name: string;
    queue_type: string;
    status: string;
    depth: number;
}

/**
 * Queue API
 *
 * NATS JetStream 기반 고신뢰 메시지 큐 API.
 * 메시지 발행, 소비, 확인(Ack), 재시도(Nack)를 지원합니다.
 *
 * @example
 * ```typescript
 * const cb = new ConnectBase({ publicKey: 'your-public-key' })
 *
 * // 메시지 발행
 * await cb.queue.publish('queue-id', {
 *     body: { to: 'user@example.com', subject: 'Welcome' }
 * })
 *
 * // 메시지 소비
 * const { messages } = await cb.queue.consume('queue-id', { max_messages: 5 })
 * for (const msg of messages) {
 *     await processMessage(msg.body)
 *     await cb.queue.ack('queue-id', [msg.message_id])
 * }
 * ```
 */
declare class QueueAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * 메시지 발행
     */
    publish(queueID: string, data: PublishMessageRequest): Promise<PublishMessageResponse>;
    /**
     * 배치 메시지 발행 (최대 100개)
     */
    publishBatch(queueID: string, data: PublishBatchRequest): Promise<PublishBatchResponse>;
    /**
     * 메시지 소비 (Pull 방식)
     *
     * auto_ack=false(기본값): 명시적 Ack 필요. 응답의 ack_token을 ack() 호출 시 전달.
     * auto_ack=true: 즉시 자동 Ack (at-most-once, 유실 가능)
     */
    consume(queueID: string, options?: ConsumeOptions): Promise<ConsumeMessagesResponse>;
    /**
     * 메시지 처리 완료 확인 (Ack)
     *
     * ackToken: auto_ack=false 소비 시 반환된 ack_token. 생략 시 message_ids로만 확인.
     */
    ack(queueID: string, messageIds: string[], ackToken?: string): Promise<void>;
    /**
     * 메시지 재시도 요청 (Nack)
     */
    nack(queueID: string, messageId: string, options?: NackMessageRequest): Promise<void>;
    /**
     * 큐 정보 조회
     */
    getInfo(queueID: string): Promise<QueueInfoResponse>;
}

/**
 * Realtime API 타입 정의
 */
/** 구독 옵션 */
interface SubscribeOptions {
    /** 히스토리 로드 개수 (persist=true인 카테고리만) */
    historyLimit?: number;
}
/** 카테고리 정보 */
interface CategoryInfo {
    category: string;
    persist: boolean;
    historyCount: number;
    readReceipt: boolean;
}
/** 메시지 데이터 */
interface RealtimeMessage<T = unknown> {
    id?: string;
    category: string;
    from?: string;
    data: T;
    sentAt: number;
}
/** 히스토리 응답 */
interface HistoryResponse<T = unknown> {
    category: string;
    messages: RealtimeMessage<T>[];
    total: number;
}
/** WebSocket 연결 상태 */
type ConnectionState = "connecting" | "connected" | "disconnected" | "reconnecting";
/** 연결 옵션 */
interface RealtimeConnectOptions {
    /** 재연결 시도 횟수 (기본: 5) */
    maxRetries?: number;
    /** 재연결 간격 (밀리초, 기본: 1000) */
    retryInterval?: number;
    /** 사용자 ID (인증된 사용자) */
    userId?: string;
    /** JWT 액세스 토큰 (앱 멤버 인증용, API Key보다 우선) */
    accessToken?: string;
    /** 연결 타임아웃 (밀리초, 기본: 30000) */
    timeout?: number;
    /** 디버그 로깅 활성화 (기본: false) */
    debug?: boolean;
    /**
     * WebSocket 핸드셰이크가 실패할 때의 fallback transport (기본: `'sse'`).
     *
     * 일부 네트워크(특정 가정용 ISP/기업 프록시/미들박스)는 HTTPS 는 통과시키면서
     * WebSocket upgrade 만 차단한다. 이 경우 `'sse'` 이면 `connect()` 가 reject 하지 않고
     * **degraded(SSE) 모드로 resolve** 하며, 이후 `stream()` 호출은 자동으로 HTTP SSE
     * (`/v1/public/ai/chat/stream`) 로 흘러 AI 스트리밍이 계속 동작한다 (앱 코드 변경 불필요).
     *
     * SSE 는 단방향(server→client)이므로 fallback 모드에서는 AI `stream()` 만 지원되고
     * presence/typing/subscribe/sendMessage 같은 양방향 기능은 명시적 에러를 던진다.
     * 현재 활성 transport 는 `cb.realtime.transport` 로 확인할 수 있다.
     *
     * `'none'` 이면 기존처럼 WS 실패 시 `connect()` 가 reject 한다.
     */
    fallback?: "sse" | "none";
}
/** 이벤트 핸들러 타입 */
type MessageHandler<T = unknown> = (message: RealtimeMessage<T>) => void;
type ErrorHandler = (error: Error) => void;
type StateChangeHandler = (state: ConnectionState) => void;
/** 메시지 전송 옵션 */
interface SendOptions {
    /** true면 발신자도 메시지를 받음 (기본값: true) */
    includeSelf?: boolean;
}
/** 구독 객체 */
interface Subscription {
    /** 카테고리 정보 */
    info: CategoryInfo;
    /** 메시지 전송 */
    send<T = unknown>(data: T, options?: SendOptions): Promise<void>;
    /** 히스토리 조회 (persist=true인 경우만) */
    getHistory<T = unknown>(limit?: number): Promise<HistoryResponse<T>>;
    /** 구독 해제 */
    unsubscribe(): Promise<void>;
    /** 메시지 수신 핸들러 등록 (반환된 함수로 핸들러 제거 가능) */
    onMessage<T = unknown>(handler: MessageHandler<T>): () => void;
}
/** 클라이언트 -> 서버 메시지 */
interface ClientMessage {
    category: string;
    action: "subscribe" | "unsubscribe" | "send" | "invoke" | "ping" | "history" | "stream" | "stream_stop" | "mark_read" | "presence_set" | "presence_on_disconnect" | "presence_get" | "presence_get_many" | "presence_subscribe" | "presence_unsubscribe" | "typing_start" | "typing_stop" | "typing_subscribe" | "typing_unsubscribe";
    data?: unknown;
    request_id: string;
}
/** 서버 -> 클라이언트 메시지 */
interface ServerMessage<T = unknown> {
    category?: string;
    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 스트리밍 메시지의 단일 텍스트 파트 (멀티모달 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 | StreamContentPart[];
}
/** AI 스트리밍 요청 옵션 */
interface StreamOptions {
    /** AI 프로바이더 (앱 설정의 프로바이더 사용. override 시 지정) */
    provider?: "gemini" | "openai" | "claude" | "ollama" | "lm_studio" | "openai_compatible";
    /** 모델명 (앱 설정의 모델을 override (선택적)) */
    model?: string;
    /** 시스템 프롬프트 */
    system?: string;
    /** 온도 (0.0-2.0, 기본: 0.7) */
    temperature?: number;
    /** 최대 토큰 수 */
    maxTokens?: number;
    /** 세션 ID (대화 추적용) */
    sessionId?: string;
    /** 사용자 정의 메타데이터 */
    metadata?: Record<string, unknown>;
    /** MCP 그룹 슬러그 (AI Agent 모드 — 등록된 MCP 서버의 도구를 AI에 제공) */
    mcpGroup?: string;
}
/** AI 스트리밍 토큰 콜백 */
type StreamTokenCallback = (token: string, index: number) => void;
/** AI 스트리밍 완료 데이터 */
interface StreamDoneData {
    sessionId: string;
    fullText: string;
    totalTokens: number;
    promptTokens: number;
    duration: number;
}
/** AI 스트리밍 완료 콜백 */
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 {
    /** 세션 ID */
    sessionId: string;
    /** 스트리밍 중지 */
    stop(): Promise<void>;
}
/** 연결 성공 데이터 */
interface ConnectedData {
    connection_id: string;
    app_id: string;
    client_id: string;
    user_id?: string;
}
/** 구독 성공 데이터 */
interface SubscribedData {
    category: string;
    persist: boolean;
    history_count: number;
    read_receipt: boolean;
}
/** 프레전스 상태 */
type PresenceStatus = "online" | "away" | "busy" | "offline";
/** 프레전스 정보 */
interface PresenceInfo {
    userId: string;
    status: PresenceStatus;
    lastSeen: number;
    device?: string;
    metadata?: Record<string, unknown>;
    eventType?: "join" | "leave" | "update";
}
/** 프레전스 설정 옵션 */
interface PresenceSetOptions {
    /** 디바이스 타입 (web, mobile, desktop 등) */
    device?: string;
    /** 사용자 정의 메타데이터 */
    metadata?: Record<string, unknown>;
}
/** 프레전스 변경 핸들러 */
type PresenceChangeHandler = (presence: PresenceInfo) => void;
/** 다수 프레전스 조회 결과 */
interface PresenceStatusResult {
    users: Record<string, PresenceInfo>;
}
/** 타이핑 정보 */
interface TypingInfo {
    roomId: string;
    users: string[];
}
/** 타이핑 변경 핸들러 */
type TypingChangeHandler = (typing: TypingInfo) => void;
/** 읽음 확인 데이터 */
interface ReadReceiptInfo {
    category: string;
    messageIds: string[];
    readerId: string;
    readAt: number;
}
/** 읽음 확인 핸들러 */
type ReadReceiptHandler = (receipt: ReadReceiptInfo) => void;

/**
 * Realtime API
 * WebSocket 기반 실시간 통신 API
 *
 * @example
 * ```typescript
 * // 연결
 * await client.realtime.connect()
 *
 * // 카테고리 구독
 * const chat = await client.realtime.subscribe('chat-room-1')
 *
 * // 메시지 수신
 * chat.onMessage((msg) => {
 *     console.log('Received:', msg.data)
 * })
 *
 * // 메시지 전송
 * await chat.send({ text: 'Hello!' })
 *
 * // 히스토리 조회 (persist=true인 카테고리만)
 * if (chat.info.persist) {
 *     const history = await chat.getHistory(50)
 *     console.log('History:', history.messages)
 * }
 *
 * // 구독 해제
 * await chat.unsubscribe()
 *
 * // 연결 해제
 * client.realtime.disconnect()
 * ```
 */
declare class RealtimeAPI {
    private http;
    private socketUrl;
    private ws;
    private state;
    private _connectionId;
    private clientId;
    private userId?;
    private _appId;
    /**
     * 현재 활성 transport.
     * - `'ws'`: WebSocket 정상 연결
     * - `'sse'`: WS 핸드셰이크 실패로 HTTP SSE fallback 모드 (AI `stream()` 만 지원)
     * - `null`: 미연결
     */
    private activeTransport;
    /** SSE fallback 모드 활성 여부. true 면 백그라운드 WS 재연결 머신을 정지한다. */
    private sseFallbackActive;
    /** SSE fallback 스트림의 AbortController (sessionId → controller) — stop()/disconnect() 에서 중단용 */
    private sseSessions;
    /** 현재 연결 ID */
    get connectionId(): string | null;
    /** 현재 연결된 앱 ID */
    get appId(): string | null;
    /**
     * 현재 활성 transport (`'ws'` | `'sse'` | `null`).
     * `'sse'` 이면 WS 가 차단되어 fallback 모드로 동작 중이며 AI `stream()` 만 가능하다.
     */
    get transport(): "ws" | "sse" | null;
    private options;
    private retryCount;
    private pendingRequests;
    private subscriptions;
    private streamSessions;
    private stateHandlers;
    private errorHandlers;
    private presenceHandlers;
    private presenceSubscriptions;
    private typingHandlers;
    private readReceiptHandlers;
    constructor(http: HttpClient, socketUrl: string);
    private connectPromise;
    /**
     * WebSocket 연결
     * @param options 연결 옵션
     * - accessToken: JWT 토큰으로 인증 (앱 멤버용, API Key보다 우선)
     * - userId: 사용자 식별자 (표시용)
     */
    connect(options?: RealtimeConnectOptions): Promise<void>;
    /**
     * SSE fallback 모드로 전환한다. WS 는 사용 불가하지만 state 는 'connected' 로 두어
     * (degraded) AI stream() 이 SSE 로 동작하게 한다. 백그라운드 WS 재연결 머신은 정지한다.
     */
    private activateSseFallback;
    /**
     * 연결 해제
     */
    disconnect(): void;
    /**
     * 카테고리 구독
     */
    subscribe(category: string, options?: SubscribeOptions): Promise<Subscription>;
    /**
     * 구독 해제
     */
    unsubscribe(category: string): Promise<void>;
    /**
     * 메시지 전송
     * @param category 카테고리 이름
     * @param data 전송할 데이터
     * @param options 전송 옵션 (includeSelf: 발신자도 메시지 수신 여부, 기본값 true)
     */
    sendMessage<T = unknown>(category: string, data: T, options?: SendOptions): Promise<void>;
    /**
     * 히스토리 조회
     */
    getHistory<T = unknown>(category: string, limit?: number): Promise<HistoryResponse<T>>;
    /**
     * AI 스트리밍
     * @param messages 대화 메시지 목록
     * @param handlers 스트리밍 핸들러 (onToken, onDone, onError)
     * @param options 스트리밍 옵션
     * @returns 스트리밍 세션 (중지 가능)
     *
     * @example
     * ```typescript
     * // 브라우저에서 사용
     * const outputEl = document.getElementById('ai-output')
     *
     * const session = await client.realtime.stream(
     *     [{ role: 'user', content: '안녕하세요' }],
     *     {
     *         onToken: (token) => {
     *             outputEl.textContent += token // 실시간 출력
     *         },
     *         onDone: (result) => {
     *             console.log('완료:', result.fullText)
     *         },
     *         onError: (error) => {
     *             console.error('에러:', error)
     *         }
     *     },
     *     { provider: 'gemini', model: 'gemini-2.0-flash', temperature: 0.7 }
     * )
     *
     * // 필요 시 중지
     * await session.stop()
     * ```
     */
    stream(messages: StreamMessage[], handlers: StreamHandlers, options?: StreamOptions): Promise<StreamSession>;
    /** WebSocket 으로 AI 스트리밍 (기본 경로) */
    private streamViaWS;
    /**
     * HTTP SSE (`/v1/public/ai/chat/stream`) 로 AI 스트리밍 — WS 가 차단된 네트워크용 fallback.
     *
     * SSE 는 단방향이라 WS 의 `StreamDoneData` 토큰 카운트(total/prompt)를 받지 못하므로
     * `totalTokens`/`promptTokens` 는 0 으로 채워진다(`fullText`/`duration` 은 정확). `mcpGroup`
     * (MCP 도구) 은 SSE fallback 에서 미지원 — 지정 시 무시되고 도구 없이 스트리밍한다.
     */
    private streamViaSSE;
    private runSseStream;
    /**
     * 스트리밍 중지
     */
    stopStream(sessionId: string): Promise<void>;
    /**
     * 연결 상태
     */
    getState(): ConnectionState;
    /**
     * 연결 여부 확인
     */
    isConnected(): boolean;
    /**
     * 상태 변경 핸들러 등록
     */
    onStateChange(handler: StateChangeHandler): () => void;
    /**
     * 에러 핸들러 등록
     */
    onError(handler: ErrorHandler): () => void;
    /**
     * 프레전스 상태 설정
     * @param status 상태 (online, away, busy, offline)
     * @param options 추가 옵션 (device, metadata)
     *
     * @example
     * ```typescript
     * await client.realtime.setPresence('online', {
     *     device: 'web',
     *     metadata: { nickname: 'John' }
     * })
     * ```
     */
    setPresence(status: PresenceStatus, options?: PresenceSetOptions): Promise<void>;
    /**
     * 연결 해제 시 자동으로 설정될 프레전스 상태 지정
     * @param status 연결 해제 시 변경할 상태
     * @param metadata 연결 해제 시 업데이트할 메타데이터
     *
     * @example
     * ```typescript
     * // 연결이 끊기면 자동으로 offline으로 변경
     * await client.realtime.setPresenceOnDisconnect('offline')
     * ```
     */
    setPresenceOnDisconnect(status: PresenceStatus, metadata?: Record<string, unknown>): Promise<void>;
    /**
     * 특정 사용자의 프레전스 조회
     * @param userId 조회할 사용자 ID
     * @returns 프레전스 정보
     *
     * @example
     * ```typescript
     * const presence = await client.realtime.getPresence('user-123')
     * console.log(presence.status) // 'online'
     * ```
     */
    getPresence(userId: string): Promise<PresenceInfo>;
    /**
     * 여러 사용자의 프레전스 조회
     * @param userIds 조회할 사용자 ID 목록
     * @returns 사용자별 프레전스 정보
     *
     * @example
     * ```typescript
     * const result = await client.realtime.getPresenceMany(['user-1', 'user-2'])
     * console.log(result.users['user-1'].status)
     * ```
     */
    getPresenceMany(userIds: string[]): Promise<PresenceStatusResult>;
    /**
     * 특정 사용자의 프레전스 변경 구독
     * @param userId 구독할 사용자 ID
     * @param handler 프레전스 변경 핸들러
     * @returns 구독 해제 함수
     *
     * @example
     * ```typescript
     * const unsubscribe = await client.realtime.subscribePresence('user-123', (presence) => {
     *     console.log(`${presence.userId} is now ${presence.status}`)
     * })
     *
     * // 나중에 구독 해제
     * unsubscribe()
     * ```
     */
    subscribePresence(userId: string, handler: PresenceChangeHandler): Promise<() => void>;
    /**
     * 전체 프레전스 변경 이벤트 구독
     * @param handler 프레전스 변경 핸들러
     * @returns 구독 해제 함수
     *
     * @example
     * ```typescript
     * const unsubscribe = client.realtime.onPresenceChange((presence) => {
     *     if (presence.eventType === 'join') {
     *         console.log(`${presence.userId} joined`)
     *     }
     * })
     * ```
     */
    onPresenceChange(handler: PresenceChangeHandler): () => void;
    /**
     * 타이핑 시작 알림
     * @param roomId 타이핑 중인 룸/채널 ID (category 이름)
     *
     * @example
     * ```typescript
     * // 입력 시작 시
     * input.addEventListener('focus', () => {
     *     client.realtime.startTyping('chat-room-1')
     * })
     * ```
     */
    startTyping(roomId: string): Promise<void>;
    /**
     * 타이핑 종료 알림
     * @param roomId 타이핑을 종료할 룸/채널 ID
     *
     * @example
     * ```typescript
     * // 입력 종료 또는 메시지 전송 시
     * input.addEventListener('blur', () => {
     *     client.realtime.stopTyping('chat-room-1')
     * })
     * ```
     */
    stopTyping(roomId: string): Promise<void>;
    /**
     * 타이핑 상태 변경 구독
     * @param roomId 구독할 룸/채널 ID
     * @param handler 타이핑 상태 변경 핸들러
     * @returns 구독 해제 함수
     *
     * @example
     * ```typescript
     * const unsubscribe = await client.realtime.onTypingChange('chat-room-1', (typing) => {
     *     if (typing.users.length > 0) {
     *         indicator.textContent = `${typing.users.join(', ')} is typing...`
     *     } else {
     *         indicator.textContent = ''
     *     }
     * })
     * ```
     */
    onTypingChange(roomId: string, handler: TypingChangeHandler): Promise<() => void>;
    /**
     * 메시지 읽음 표시
     * @param category 카테고리 이름
     * @param messageIds 읽음 처리할 메시지 ID 목록
     *
     * @example
     * ```typescript
     * // 메시지를 읽었을 때
     * await client.realtime.markRead('chat-room-1', ['msg-1', 'msg-2'])
     * ```
     */
    markRead(category: string, messageIds: string[]): Promise<void>;
    /**
     * 읽음 확인 이벤트 구독
     * @param category 구독할 카테고리 이름
     * @param handler 읽음 확인 핸들러
     * @returns 구독 해제 함수
     *
     * @example
     * ```typescript
     * const unsubscribe = client.realtime.onReadReceipt('chat-room-1', (receipt) => {
     *     console.log(`${receipt.readerId} read messages: ${receipt.messageIds.join(', ')}`)
     * })
     * ```
     */
    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;
    /**
     * 이전 구독 상태를 복구합니다.
     * 재연결 성공 후 호출됩니다.
     */
    private restoreSubscriptions;
    /**
     * 양방향(WS 전용) 기능을 SSE fallback 모드에서 호출하면 명확한 에러를 던진다.
     * SSE 는 단방향이라 presence/typing/subscribe/sendMessage 를 지원하지 못한다.
     */
    private assertBidirectional;
    private sendRequest;
    private sendRaw;
    private notifyStateChange;
    private notifyError;
    private generateClientId;
    private generateRequestId;
}

/** 역할 목록 항목. 백엔드 `fetchRoleItem` 매핑. */
interface RoleListItem {
    id: string;
    role_title: string;
    role_description: string;
    create_time: string;
    permission_count: number;
    user_count: number;
}
/** `cb.roles.list` 반환값. 백엔드 `FetchRolesResponse` 매핑. */
interface RoleList {
    total_count: number;
    role_list: RoleListItem[];
}
/** 역할이 가진 권한 항목. */
interface RolePermissionItem {
    id: number;
    name: string;
    category: string;
    description: string;
}
/** 역할에 할당된 사용자 항목. */
interface RoleUserItem {
    id: string;
    nickname: string;
    email: string | null;
    assign_time: string;
}
/** `cb.roles.get` 반환값. 백엔드 `FetchRoleDetailResponse` 매핑. */
interface RoleDetail {
    role_name: string;
    role_description: string;
    create_time: string;
    permission_item: RolePermissionItem[];
    user_item: RoleUserItem[];
}
/** `cb.roles.create` 페이로드. */
interface CreateRolePayload {
    title: string;
    description: string;
    /** 생성과 동시에 부여할 권한 ID 목록 (선택). 없으면 빈 역할로 생성. */
    permissionIds?: number[];
}
/** `cb.roles.create` 반환값. */
interface CreateRoleResult {
    id: string;
    role_title: string;
    role_description: string;
}
/**
 * `cb.roles.update` 페이로드. 백엔드 EditRole 은 **전체 동기화(replace)** 라 모든 필드가 필수다 —
 * permissionIds / userIds 는 "이 역할이 가질 전체"를 의미하며, 전달값으로 완전히 대체된다.
 * 사용자만 바꾸고 나머지를 보존하려면 `assign` 을 쓰거나 `get` 으로 현재 값을 읽어 합쳐라.
 */
interface UpdateRolePayload {
    title: string;
    description: string;
    /** 이 역할이 가질 권한 ID 전체 (동기화). */
    permissionIds: number[];
    /** 이 역할을 가질 사용자 ID 전체 (동기화). */
    userIds: string[];
}
/**
 * 앱 역할(RBAC) 관리 API — 서버사이드 전용.
 *
 * service_role 함수(ctx.cbAdmin) 또는 콘솔 JWT 인증이 필요하며, Public Key(cb_pk_) 단독 브라우저
 * SDK 인스턴스로는 호출할 수 없다. service_role 함수에서 쓰려면 management_scopes 가 필요하다 —
 * 조회(list/get)는 `role:read`, 변경(create/update/assign/delete)은 `role:manage`.
 *
 * @example
 * ```typescript
 * // 함수(service_role, management_scopes: ["role:read","role:manage"]) 안에서
 * const roles = await ctx.cbAdmin.roles.list(ctx.appId)
 * const { id } = await ctx.cbAdmin.roles.create(ctx.appId, { title: '읽기전용 운영자', description: '조회만' })
 * await ctx.cbAdmin.roles.assign(ctx.appId, id, ['user-uuid-1', 'user-uuid-2'])
 * ```
 */
declare class RolesAPI {
    private http;
    constructor(http: HttpClient);
    private ensureServerAuth;
    /** 앱의 역할 목록을 조회한다. (management_scope: `role:read`) */
    list(appId: string): Promise<RoleList>;
    /** 역할 상세(권한/할당 사용자 포함)를 조회한다. (management_scope: `role:read`) */
    get(appId: string, roleId: string): Promise<RoleDetail>;
    /** 역할을 생성한다. (management_scope: `role:manage`) */
    create(appId: string, payload: CreateRolePayload): Promise<CreateRoleResult>;
    /**
     * 역할을 수정한다 — **전체 동기화(replace)**. permissionIds / userIds 는 전달값으로 대체된다.
     * (management_scope: `role:manage`)
     */
    update(appId: string, roleId: string, payload: UpdateRolePayload): Promise<void>;
    /**
     * 역할에 사용자를 할당한다 (제목/설명/권한 보존). EditRole 이 전체 동기화라, 현재 상세를 읽어
     * 나머지 필드를 유지한 채 사용자 목록만 교체해 PUT 한다. userIds 는 "이 역할을 가질 사용자
     * 전체"다 (추가가 아니라 동기화). (management_scope: `role:manage`)
     */
    assign(appId: string, roleId: string, userIds: string[]): Promise<void>;
    /** 역할을 삭제한다. (management_scope: `role:manage`) */
    delete(appId: string, roleId: string): Promise<void>;
}

interface FileItem {
    id: string;
    name: string;
    path: string;
    type: "file" | "folder";
    mime_type?: string;
    size: number;
    url?: string;
    parent_id?: string;
    children?: FileItem[];
    created_at: string;
    updated_at: string;
}
interface UploadFileResponse {
    id: string;
    name: string;
    path: string;
    type: string;
    mime_type: string;
    size: number;
    url: string;
    parent_id?: string;
    created_at: string;
}
interface CreateFolderRequest {
    name: string;
    parent_id?: string;
}
interface CreateFolderResponse {
    id: string;
    name: string;
    path: string;
    type: string;
    parent_id?: string;
    created_at: string;
}
interface MoveFileRequest {
    new_parent_id?: string;
}
interface RenameFileRequest {
    name: string;
}
interface RenameFileResponse {
    id: string;
    name: string;
    path: string;
}
interface FetchFilesResponse {
    files: FileItem[];
}
/**
 * 파일 업로드 진행률 (바이트 단위).
 *
 * presigned URL 로의 직접 PUT 은 단일 요청이라 청크 개념이 없어,
 * 영상 업로드(`UploadProgress`, 청크 기반)와 달리 바이트 기준으로 보고한다.
 * `percentage` 필드명은 영상 업로드와 통일했다.
 */
interface StorageUploadProgress {
    /** 지금까지 업로드된 바이트 */
    loaded: number;
    /** 전체 바이트 (= file.size) */
    total: number;
    /** 0~100 정수 백분율 */
    percentage: number;
}
/**
 * 파일 업로드 옵션 (`uploadFile` / `uploadFiles`).
 *
 * 기존 `uploadFile(storageId, file, parentId)` 시그니처와 하위 호환을 위해
 * 3번째 인자는 문자열(parentId) 또는 이 옵션 객체를 모두 받는다.
 */
interface UploadFileOptions {
    /** 부모 폴더 ID (기존 3번째 인자와 동일 의미) */
    parentId?: string;
    /**
     * 업로드 진행률 콜백. 브라우저 환경(XMLHttpRequest 사용 가능)에서만
     * 바이트 단위 진행률을 실시간으로 받는다. Node/Edge 등 XHR 이 없는
     * 환경에서는 시작(0%)/완료(100%)만 통지한다.
     */
    onProgress?: (progress: StorageUploadProgress) => void;
    /** 업로드 취소용 외부 AbortSignal */
    signal?: AbortSignal;
    /**
     * PUT 요청 타임아웃(ms). 기본 30초. 대용량 파일은 이보다 오래 걸릴 수
     * 있으므로 필요 시 늘린다. 0 또는 무한대면 타임아웃을 두지 않는다.
     */
    timeout?: number;
}
/**
 * 경로 기반 업로드 옵션
 */
interface UploadByPathOptions {
    /** true면 기존 파일 덮어쓰기 (기본값: true) */
    overwrite?: boolean;
    /**
     * 업로드 진행률 콜백. 동작은 {@link UploadFileOptions.onProgress} 와 동일하다.
     */
    onProgress?: (progress: StorageUploadProgress) => void;
    /** 업로드 취소용 외부 AbortSignal */
    signal?: AbortSignal;
    /** PUT 요청 타임아웃(ms). 기본 30초. */
    timeout?: number;
}
/**
 * 경로로 파일 조회 응답
 */
interface GetFileByPathResponse {
    id: string;
    name: string;
    path: string;
    type: string;
    mime_type: string;
    size: number;
    url: string;
    parent_id?: string;
    created_at: string;
    updated_at: string;
}
/**
 * 페이지 메타 설정 요청 (OG 태그, JSON-LD 등)
 */
interface SetPageMetaRequest {
    /** 페이지 경로 (예: /products/123) */
    path: string;
    /** OG 타이틀 */
    title?: string;
    /** OG 설명 */
    description?: string;
    /** OG 이미지 URL */
    image?: string;
    /** OG 타입 (website, article, product 등) */
    og_type?: string;
    /** JSON-LD 구조화 데이터 */
    json_ld?: string;
    /** sitemap.xml 포함 여부 (기본: true) */
    include_in_sitemap?: boolean;
    /** 사이트맵 우선순위 (0.0~1.0) */
    sitemap_priority?: number;
    /** 캐노니컬 URL */
    canonical_url?: string;
    /** 검색엔진 noindex 설정 (true면 검색 결과에서 제외) */
    robots_noindex?: boolean;
}
/**
 * 페이지 메타 응답
 */
interface PageMetaResponse {
    id: string;
    storage_web_id: string;
    path: string;
    title: string;
    description: string;
    image: string;
    og_type: string;
    json_ld?: string;
    include_in_sitemap: boolean;
    sitemap_priority: number;
    canonical_url?: string;
    robots_noindex: boolean;
    created_at: string;
    updated_at: string;
}
/**
 * 페이지 메타 목록 조회 옵션
 */
interface ListPageMetasOptions {
    /** 한 페이지에 가져올 최대 개수 (기본: 20, 최대: 100) */
    limit?: number;
    /** 건너뛸 개수 (기본: 0) */
    offset?: number;
}
/**
 * 페이지 메타 목록 응답
 */
interface ListPageMetasResponse {
    total_count: number;
    limit: number;
    offset: number;
    pages: PageMetaResponse[];
}
/**
 * 여러 페이지 메타 일괄 설정 요청
 */
interface BatchSetPageMetaRequest {
    pages: SetPageMetaRequest[];
}
/**
 * Presigned URL 생성 요청
 */
interface GenerateUploadURLRequest {
    file_name: string;
    file_size: number;
    mime_type: string;
    parent_id?: string;
}
/**
 * Presigned URL 생성 응답
 */
interface GenerateUploadURLResponse {
    upload_url: string;
    file_id: string;
    public_url: string;
}
/**
 * 경로 기반 Presigned URL 생성 요청
 */
interface GenerateUploadURLByPathRequest {
    file_name: string;
    file_size: number;
    mime_type: string;
    overwrite?: boolean;
}
/**
 * 업로드 완료 요청
 */
interface CompleteUploadRequest {
    file_id: string;
}
/**
 * 업로드 완료 응답
 */
interface CompleteUploadResponse {
    id: string;
    name: string;
    path: string;
    type: string;
    mime_type: string;
    size: number;
    url: string;
    parent_id?: string;
    created_at: string;
}

declare class StorageAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * Presigned URL 로 직접 업로드. 호출 전에 URL 스킴(https)을 검증해
     * 서버 응답을 그대로 신뢰하는 SSRF/오용 경로를 차단.
     * 타임아웃과 외부 signal 을 모두 지원한다.
     *
     * `onProgress` 가 주어지고 `XMLHttpRequest` 를 쓸 수 있는(브라우저) 환경이면
     * XHR 의 `upload.onprogress` 로 바이트 단위 진행률을 보고한다. 그 외에는
     * fetch 로 업로드하고 시작(0%)/완료(100%)만 통지한다(Node/Edge 호환).
     */
    private uploadToPresigned;
    /**
     * XMLHttpRequest 기반 PUT 업로드. `upload.onprogress` 로 바이트 진행률을
     * 보고하며, 외부 signal(취소)과 타임아웃을 모두 지원한다. URL 은 호출 전에
     * 이미 검증된 값을 받는다(uploadToPresigned 에서 스킴 검증 수행).
     */
    private putViaXhr;
    /**
     * 파일 목록 조회
     *
     * @param storageId - 파일 스토리지 ID
     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
     *
     * @example
     * ```ts
     * // 스토리지 전체 파일 목록 (flat 트리)
     * const files = await cb.storage.getFiles('storage-id')
     *
     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
     * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
     * ```
     */
    getFiles(storageId: string, parentId?: string): Promise<FileItem[]>;
    /**
     * 파일 업로드 (Presigned URL 방식)
     *
     * 서버를 거치지 않고 Object Storage에 직접 업로드합니다.
     *
     * 3번째 인자는 부모 폴더 ID(문자열) 또는 옵션 객체를 받습니다. 옵션으로
     * `onProgress` 콜백을 넘기면 업로드 진행률(%)을 실시간으로 받을 수 있습니다
     * (브라우저 환경). 기존 `uploadFile(id, file, 'folder-id')` 호출과 하위 호환됩니다.
     *
     * @example
     * ```ts
     * const fileInput = document.querySelector('input[type="file"]')
     * const result = await cb.storage.uploadFile('storage-id', fileInput.files[0])
     * console.log(result.url) // 업로드된 파일 URL
     *
     * // 특정 폴더에 업로드 (기존 방식 그대로)
     * await cb.storage.uploadFile('storage-id', file, 'folder-id')
     *
     * // 진행률 표시 + 특정 폴더
     * await cb.storage.uploadFile('storage-id', file, {
     *   parentId: 'folder-id',
     *   onProgress: (p) => console.log(`${p.percentage}%`), // { loaded, total, percentage }
     * })
     * ```
     */
    uploadFile(storageId: string, file: File, parentIdOrOptions?: string | UploadFileOptions): Promise<UploadFileResponse>;
    /**
     * 여러 파일 업로드
     *
     * `onProgress` 를 옵션으로 넘기면 **파일별로** 진행률 콜백이 호출됩니다
     * (각 파일마다 0→100%). 전체 진행률이 필요하면 완료된 파일 수를 직접 집계하세요.
     */
    uploadFiles(storageId: string, files: File[], parentIdOrOptions?: string | UploadFileOptions): Promise<UploadFileResponse[]>;
    /**
     * 폴더 생성
     */
    createFolder(storageId: string, data: CreateFolderRequest): Promise<CreateFolderResponse>;
    /**
     * 파일/폴더 삭제
     */
    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>;
    /**
     * 파일 URL 가져오기
     */
    getFileUrl(file: FileItem): string | null;
    /**
     * 이미지 파일 여부 확인
     */
    isImageFile(file: FileItem): boolean;
    /**
     * 경로 기반 파일 업로드 (Firebase Storage 스타일, Presigned URL)
     *
     * 같은 경로에 파일이 이미 존재하면 덮어쓰기합니다.
     * URL이 변경되지 않아 고정 URL이 필요한 경우에 유용합니다.
     *
     * @example
     * ```ts
     * // 프로필 이미지 업로드 (항상 같은 URL 유지)
     * const result = await storage.uploadByPath(
     *   storageId,
     *   '/profiles/user123/avatar.png',
     *   file
     * )
     * console.log(result.url) // 항상 동일한 URL
     *
     * // 같은 경로로 다시 업로드하면 파일만 교체
     * await storage.uploadByPath(storageId, '/profiles/user123/avatar.png', newFile)
     * ```
     */
    uploadByPath(storageId: string, path: string, file: File, options?: UploadByPathOptions): Promise<UploadFileResponse>;
    /**
     * 경로로 파일 조회
     *
     * @example
     * ```ts
     * const file = await storage.getByPath(storageId, '/profiles/user123/avatar.png')
     * console.log(file.url) // 파일의 공개 URL
     * ```
     */
    getByPath(storageId: string, path: string): Promise<GetFileByPathResponse>;
    /**
     * 경로로 파일 URL 가져오기
     *
     * 파일이 존재하지 않으면 null 반환
     *
     * @example
     * ```ts
     * const url = await storage.getUrlByPath(storageId, '/profiles/user123/avatar.png')
     * if (url) {
     *   console.log('이미지 URL:', url)
     * }
     * ```
     */
    getUrlByPath(storageId: string, path: string): Promise<string | null>;
    /**
     * 페이지 메타 설정 (Upsert)
     *
     * 소셜 미디어 공유 시 표시되는 OG 태그, JSON-LD 구조화 데이터 등을 설정합니다.
     * 같은 경로에 이미 메타 정보가 있으면 업데이트됩니다.
     *
     * @example
     * ```ts
     * // 상품 페이지 OG 태그 설정
     * await cb.storage.setPageMeta('web-storage-id', {
     *   path: '/products/123',
     *   title: '최신 스마트폰 - 내 쇼핑몰',
     *   description: '최고의 성능, 최저가 보장',
     *   image: 'https://example.com/product.jpg',
     *   og_type: 'product',
     *   json_ld: JSON.stringify({
     *     "@context": "https://schema.org",
     *     "@type": "Product",
     *     "name": "최신 스마트폰",
     *     "image": "https://example.com/product.jpg",
     *     "offers": { "@type": "Offer", "price": "999000", "priceCurrency": "KRW" }
     *   })
     * })
     * ```
     */
    setPageMeta(webStorageId: string, data: SetPageMetaRequest): Promise<PageMetaResponse>;
    /**
     * 여러 페이지 메타 일괄 설정 (최대 100개)
     *
     * @example
     * ```ts
     * await cb.storage.batchSetPageMeta('web-storage-id', {
     *   pages: [
     *     { path: '/products/1', title: '상품 1', description: '설명 1' },
     *     { path: '/products/2', title: '상품 2', description: '설명 2' },
     *   ]
     * })
     * ```
     */
    batchSetPageMeta(webStorageId: string, data: BatchSetPageMetaRequest): Promise<ListPageMetasResponse>;
    /**
     * 페이지 메타 목록 조회 (페이지네이션 지원)
     *
     * @example
     * ```ts
     * // 기본 조회 (최대 20개)
     * const { total_count, pages } = await cb.storage.listPageMetas('web-storage-id')
     *
     * // 페이지네이션
     * const page2 = await cb.storage.listPageMetas('web-storage-id', { limit: 10, offset: 10 })
     * ```
     */
    listPageMetas(webStorageId: string, options?: ListPageMetasOptions): Promise<ListPageMetasResponse>;
    /**
     * 특정 경로의 페이지 메타 조회
     */
    getPageMeta(webStorageId: string, path: string): Promise<PageMetaResponse>;
    /**
     * 특정 경로의 페이지 메타 삭제
     */
    deletePageMeta(webStorageId: string, path: string): Promise<void>;
    /**
     * 웹 스토리지의 모든 페이지 메타 삭제
     */
    deleteAllPageMetas(webStorageId: string): Promise<void>;
}

interface IssueBillingKeyRequest {
    /** 토스 인증 키 (카드 등록 후 받은 키) */
    auth_key: string;
    /** 고객 이메일 */
    customer_email?: string;
    /** 고객 이름 */
    customer_name?: string;
    /** 고객 전화번호 */
    customer_phone?: string;
    /** 기본 결제 수단으로 설정 */
    is_default?: boolean;
}
interface IssueBillingKeyResponse {
    /** 빌링키 등록을 위한 URL */
    auth_url: string;
    /** 고객 키 (토스에서 사용) */
    customer_key: string;
    /** 토스 클라이언트 키 */
    toss_client_key: string;
}
interface ConfirmBillingKeyRequest {
    /** 고객 키 */
    customer_key: string;
    /** 토스 인증 키 */
    auth_key: string;
    /** 고객 이메일 */
    customer_email?: string;
    /** 고객 이름 */
    customer_name?: string;
    /** 고객 전화번호 */
    customer_phone?: string;
    /** 기본 결제 수단으로 설정 */
    is_default?: boolean;
}
interface BillingKeyResponse {
    /** 빌링키 ID */
    id: string;
    /** 고객 키 */
    customer_key: string;
    /** 카드사 */
    card_company: string;
    /** 마스킹된 카드 번호 */
    card_number: string;
    /** 카드 타입 (신용/체크) */
    card_type: string;
    /** 카드 별명 */
    card_nickname: string;
    /** 기본 결제 수단 여부 */
    is_default: boolean;
    /** 활성 여부 */
    is_active: boolean;
    /** 고객 이메일 */
    customer_email: string;
    /** 고객 이름 */
    customer_name: string;
    /** 인증 일시 */
    authenticated_at: string;
    /** 생성 일시 */
    created_at: string;
}
interface UpdateBillingKeyRequest {
    /** 카드 별명 */
    card_nickname?: string;
    /** 기본 결제 수단 여부 */
    is_default?: boolean;
}
interface ListBillingKeysResponse {
    billing_keys: BillingKeyResponse[];
}
type BillingCycle = "daily" | "weekly" | "monthly" | "yearly";
type SubscriptionStatus = "active" | "paused" | "canceled" | "past_due" | "expired" | "trial";
interface CreateSubscriptionRequest {
    /** 빌링키 ID (toss/stripe 필수, payapp 미사용 — payurl 모델) */
    billing_key_id?: string;
    /** 플랜 이름 */
    plan_name: string;
    /** 플랜 설명 */
    plan_description?: string;
    /** 결제 금액 */
    amount: number;
    /** 통화 (기본: KRW) */
    currency?: string;
    /** 결제 주기 */
    billing_cycle: BillingCycle;
    /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
    billing_day?: number;
    /** 트라이얼 기간 (일) */
    trial_days?: number;
    /** 고객 이메일 */
    customer_email?: string;
    /** 고객 이름 */
    customer_name?: string;
    /** 고객 전화번호 (payapp 정기결제 필수 — rebillRegist recvphone) */
    customer_phone?: string;
    /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
    expire_date?: string;
    /** MoR 필수: PG 카탈로그의 recurring price/product ref (Paddle `pri_*` / Dodo `pdt_*`) */
    provider_price_ref?: string;
    /**
     * 사용할 자격증명 모드 오버라이드 (test|live). 단건결제 `prepare()` 의 `payment_mode` 와
     * 적용 조건이 **완전히 동일**하다 — 서버 시크릿 키(`cb_sk_*`)로 승격된 호출에서만 적용되고,
     * 브라우저 공개 키(`cb_pk_*`) 호출에서는 무시된다.
     *
     * 모드 결정 우선순위: 이 오버라이드 → 퍼블릭 키에 고정된 모드 → 앱 결제 설정의 프로바이더 모드
     * → test. 브라우저 앱에서 QA/프로덕션을 나누려면 이 필드가 아니라 키 단위 모드를 쓴다.
     *
     * 구독은 생성 시점 모드가 고정되므로 이후 갱신 청구·해지도 같은 키로 처리된다.
     */
    payment_mode?: "test" | "live";
    /** 메타데이터 */
    metadata?: Record<string, unknown>;
}
interface SubscriptionResponse {
    /** 구독 ID (UUID) */
    id: string;
    /** 구독 ID (문자열) */
    subscription_id: string;
    /** 결제 프로바이더 */
    provider?: "toss" | "stripe" | "payapp" | "paypal" | "paddle" | "dodo";
    /** payapp: 카드등록+1회차 결제창 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
    payapp_pay_url?: string;
    /** paypal: 구독 승인+결제수단 등록 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
    paypal_approve_url?: string;
    /** paddle: Paddle.js Checkout.open({transactionId})로 오버레이. 확정은 웹훅이 SoT */
    provider_ref?: string;
    /** paddle: Paddle.js 초기화용 client-side token */
    client_token?: string;
    /** paddle: sandbox | production */
    environment?: string;
    /** paddle: 호스티드 결제 페이지 URL (fallback) */
    checkout_url?: string;
    launch_mode?: "overlay" | "redirect";
    /** paddle: 현재 구독이 물린 recurring price ID (pri_*) */
    provider_price_ref?: string;
    /** 플랜 이름 */
    plan_name: string;
    /** 플랜 설명 */
    plan_description: string;
    /**
     * 이 구독이 고정한 자격증명 모드 (test=테스트 키 | live=실결제).
     *
     * 생성 시점 값이 박히므로 이후 앱 모드를 바꿔도 갱신 청구는 원래 키로 처리된다.
     * **프로바이더 중립 필드**라 목록에서 테스트 구독과 실구독을 가르는 데 이 필드를 쓴다
     * (`environment` 는 Paddle 의 sandbox|production 이라 다른 프로바이더에서는 기대할 수 없다).
     */
    payment_mode?: "test" | "live";
    /**
     * 정기 청구 단가 (`currency` 기준 최소단위).
     *
     * MoR(Paddle/Dodo)은 상품 통화와 고객 표시통화가 다를 수 있으므로(adaptive currency),
     * 이 값을 해석할 때는 반드시 `currency` 를 함께 봐야 한다. 앱의 기본 통화를 가정하면
     * 거짓 금액이 된다(예: $10.10 을 ₩1,010 으로 표기).
     */
    amount: number;
    /** `amount` 의 통화 (ISO 4217) */
    currency: string;
    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 프로바이더가 제공할 때만) */
    country?: string;
    /** 결제 주기 */
    billing_cycle: BillingCycle;
    /** 결제일 */
    billing_day: number;
    /** 구독 상태 */
    status: SubscriptionStatus;
    /** 구독 시작일 */
    started_at: string;
    /** 현재 기간 시작일 */
    current_period_start: string;
    /** 현재 기간 종료일 */
    current_period_end: string;
    /** 다음 결제일 */
    next_billing_at: string | null;
    /** 취소일 */
    canceled_at: string | null;
    /** 종료일 */
    ended_at: string | null;
    /** 트라이얼 종료일 */
    trial_end_at: string | null;
    /**
     * 총 결제 금액 — 결제 이력 금액의 합이며 **각 결제의 표시통화** 기준이다.
     * 위 `currency` 와 다를 수 있으므로, 통화별 정확한 집계는 결제 이력의 `currency` 로 그룹핑할 것.
     */
    total_paid: number;
    /** 결제 횟수 */
    payment_count: number;
    /** 고객 이메일 */
    customer_email: string;
    /** 고객 이름 */
    customer_name: string;
    /** 메타데이터 */
    metadata: Record<string, unknown> | null;
    /** 빌링키 정보 */
    billing_key?: BillingKeyResponse;
    /** 생성 일시 */
    created_at: string;
    /** 수정 일시 */
    updated_at: string;
}
interface UpdateSubscriptionRequest {
    /** 새 빌링키 ID */
    billing_key_id?: string;
    /** 플랜 이름 */
    plan_name?: string;
    /** 플랜 설명 */
    plan_description?: string;
    /** 결제 금액 */
    amount?: number;
    /** 메타데이터 */
    metadata?: Record<string, unknown>;
}
interface PauseSubscriptionRequest {
    /** 일시정지 사유 */
    reason?: string;
}
interface CancelSubscriptionRequest {
    /** 취소 사유 */
    reason?: string;
    /** 즉시 취소 여부 (false면 현재 기간 종료 후 취소) */
    immediate?: boolean;
}
/**
 * 요금제 스왑 시 남은 금액 정산 방식 (Paddle proration_billing_mode).
 *
 * - `prorated_immediately`: 신·구 플랜 차액을 지금 일할 청구하고 즉시 전환 (업그레이드 기본).
 * - `prorated_next_billing_period`: 차액을 계산하되 다음 청구일에 부과 (전환은 즉시). 다운그레이드에 적합.
 * - `full_immediately`: 새 플랜 전액을 지금 청구.
 * - `full_next_billing_period`: 새 플랜 전액을 다음 청구일에 부과.
 * - `do_not_bill`: 전환만 하고 청구하지 않음.
 */
/**
 * 요금제 스왑 시 남은 금액 정산 방식.
 *
 * **프로바이더별 지원 범위가 다르다.** 미지원 값은 근사 대체 없이 400
 * `invalid_proration_mode` 로 거절된다 — "다음 청구일에 부과"를 조용히 "지금 청구"로 바꾸면
 * 요청하지 않은 즉시 출금이 발생하기 때문이다.
 *
 * | 값 | Paddle | Dodo |
 * | --- | --- | --- |
 * | `prorated_immediately` (기본) | ✅ | ✅ |
 * | `full_immediately` | ✅ | ✅ |
 * | `do_not_bill` | ✅ | ✅ |
 * | `prorated_next_billing_period` | ✅ | ❌ |
 * | `full_next_billing_period` | ✅ | ❌ |
 * | `difference_immediately` | ❌ | ✅ |
 */
type ProrationMode = "prorated_immediately" | "prorated_next_billing_period" | "full_immediately" | "full_next_billing_period" | "difference_immediately" | "do_not_bill";
/**
 * 즉시청구(prorated/full_immediately) 실패 시 플랜 변경을 적용할지.
 *
 * - `prevent_change`(기본): 청구 실패 시 플랜 변경 미적용 (옛 플랜 유지). 셀프서비스 안전 기본.
 * - `apply_change`: 청구 실패해도 플랜 변경 적용 (차액은 past_due 로 나중 수금). CS/관리자 흐름용.
 */
type OnPaymentFailure = "prevent_change" | "apply_change";
/**
 * 요금제 스왑(플랜 변경) 요청 — MoR(Paddle/Dodo) 구독 전용.
 *
 * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
 * proration 으로 정산한다. 예) 혼자→가족 in-place 업그레이드.
 *
 * toss/stripe/payapp/paypal 구독은 PG 네이티브 proration 이 없어 400
 * `plan_change_unsupported` 다.
 */
interface ChangePlanRequest {
    /** 새 recurring price/product ref (Paddle `pri_*` / Dodo `pdt_*`) — 필수 */
    provider_price_ref: string;
    /** 우리 표시용 플랜명 (선택) */
    plan_name?: string;
    /** 우리 표시용 플랜 설명 (선택) */
    plan_description?: string;
    /** 우리 기록용 정기 금액 (선택 — 미지정 시 PG 값으로 자동 수렴) */
    amount?: number;
    /** 정산 방식 (기본: prorated_immediately) */
    proration_mode?: ProrationMode;
    /** 즉시청구 실패 시 처리 (기본: prevent_change) */
    on_payment_failure?: OnPaymentFailure;
    /** 메타데이터 병합 (선택) */
    metadata?: Record<string, unknown>;
}
/**
 * 요금제 스왑 미리보기 응답 — 실제 적용 없이 정산 결과만 계산.
 *
 * `immediate_charge_amount` 는 세금·기존 크레딧 잔액까지 반영된 PG 계산값(권위)이다.
 * 확정 화면에 "지금 ₩X 청구, 이후 ₩Y/주기" 로 그대로 노출한다(직접 차액을 계산하지 말 것).
 *
 * **통화가 둘인 이유**: 즉시청구는 고객 표시통화로, 정기 단가는 상품 통화로 계산된다. MoR 의
 * adaptive currency 에서 이 둘이 다를 수 있어 각각 통화를 싣는다. 금액을 표시할 때는 반드시
 * 짝이 되는 통화 필드를 함께 써야 한다 — 하나의 통화로 뭉치면 확정 직전 화면에 거짓 금액이 뜬다.
 */
interface ChangePlanPreview {
    /** 적용된 정산 모드 */
    proration_mode: ProrationMode;
    /** 지금 발생: charge(청구) | credit(크레딧) | 없음 */
    immediate_charge_action?: "charge" | "credit";
    /** 지금 순액(minor). 청구=양수, 크레딧=음수 */
    immediate_charge_amount: number;
    /** `immediate_charge_amount` 의 통화 (ISO 4217) */
    currency: string;
    /** 새 플랜의 다음 정기 청구액(minor) */
    recurring_amount: number;
    /** `recurring_amount` 의 통화. 비어 있으면 `currency` 와 동일 */
    recurring_currency?: string;
    /** 즉시청구의 정산통화 환산액 (MoR 제공 시) — 매출 대사용, 고객 표시에는 쓰지 말 것 */
    settlement_amount?: number;
    /** `settlement_amount` 의 통화 */
    settlement_currency?: string;
    /** 다음 청구 예정일 */
    next_billed_at?: string | null;
    /** 미리보기가 반영한 새 price/product ref */
    new_provider_price_ref?: string;
}
interface ListSubscriptionsRequest {
    /** 상태 필터 */
    status?: SubscriptionStatus;
    /** 페이지 크기 */
    limit?: number;
    /** 오프셋 */
    offset?: number;
}
interface ListSubscriptionsResponse {
    subscriptions: SubscriptionResponse[];
    total: number;
    limit: number;
    offset: number;
}
type SubscriptionPaymentStatus = "pending" | "done" | "failed" | "canceled";
interface SubscriptionPaymentResponse {
    /** 결제 ID */
    id: string;
    /** 구독 ID */
    subscription_id: string;
    /** 이 청구를 처리한 결제 프로바이더 */
    provider?: string;
    /** 토스 결제 키 */
    payment_key: string;
    /** 주문 ID */
    order_id: string;
    /** 결제 금액 — 고객이 실제 청구받은 **표시통화** 기준 */
    amount: number;
    /** `amount` 의 통화 (ISO 4217) */
    currency: string;
    /** 정산통화 환산액 (MoR 제공 시) — 매출 대사용, 고객 표시에는 쓰지 말 것 */
    settlement_amount?: number;
    /** `settlement_amount` 의 통화 */
    settlement_currency?: string;
    /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
    country?: string;
    /** 결제 상태 */
    status: SubscriptionPaymentStatus;
    /** 기간 시작일 */
    period_start: string;
    /** 기간 종료일 */
    period_end: string;
    /** 결제 일시 */
    paid_at: string | null;
    /** 영수증 URL */
    receipt_url: string;
    /** 실패 코드 */
    failure_code: string;
    /** 실패 메시지 */
    failure_message: string;
    /** 재시도 횟수 */
    retry_count: number;
    /** 카드사 */
    card_company: string;
    /** 카드 번호 */
    card_number: string;
    /** 생성 일시 */
    created_at: string;
}
interface ListSubscriptionPaymentsRequest {
    /** 상태 필터 */
    status?: SubscriptionPaymentStatus;
    /** 페이지 크기 */
    limit?: number;
    /** 오프셋 */
    offset?: number;
}
interface ListSubscriptionPaymentsResponse {
    payments: SubscriptionPaymentResponse[];
    total: number;
    limit: number;
    offset: number;
}
interface ChargeWithBillingKeyRequest {
    /** 빌링키 ID */
    billing_key_id: string;
    /** 결제 금액 */
    amount: number;
    /** 상품명 */
    order_name: string;
    /** 주문 ID (선택) */
    order_id?: string;
    /** 고객 이메일 */
    customer_email?: string;
    /** 고객 이름 */
    customer_name?: string;
    /** 메타데이터 */
    metadata?: Record<string, unknown>;
}
interface ChargeWithBillingKeyResponse {
    /** 토스 결제 키 */
    payment_key: string;
    /** 주문 ID */
    order_id: string;
    /** 결제 금액 */
    amount: number;
    /** 결제 상태 */
    status: string;
    /** 영수증 URL */
    receipt_url: string;
    /** 승인 일시 */
    approved_at: string | null;
    /** 카드사 */
    card_company: string;
    /** 카드 번호 */
    card_number: string;
}

declare class SubscriptionAPI {
    private http;
    constructor(http: HttpClient);
    /**
     * API Key 인증 시 /v1/public 접두사 반환
     */
    private getPublicPrefix;
    /**
     * 빌링키 발급 시작
     * 토스 카드 등록 위젯에 필요한 정보를 반환합니다.
     *
     * @returns 토스 클라이언트 키, 고객 키 등
     *
     * @example
     * ```typescript
     * const result = await client.subscription.issueBillingKey()
     *
     * // 토스 카드 등록 위젯
     * const tossPayments = TossPayments(result.toss_client_key)
     * await tossPayments.requestBillingAuth('카드', {
     *     customerKey: result.customer_key,
     *     successUrl: 'https://mysite.com/billing/success',
     *     failUrl: 'https://mysite.com/billing/fail'
     * })
     * ```
     */
    issueBillingKey(): Promise<IssueBillingKeyResponse>;
    /**
     * 빌링키 등록 확인
     * 토스에서 카드 등록 완료 후 빌링키를 확정합니다.
     *
     * @param data - 등록 확인 정보
     * @returns 등록된 빌링키 정보
     *
     * @example
     * ```typescript
     * const billingKey = await client.subscription.confirmBillingKey({
     *     customer_key: 'cust_xxxxx',
     *     auth_key: 'auth_xxxxx',
     *     customer_email: 'test@example.com',
     *     customer_name: '홍길동',
     *     is_default: true
     * })
     * ```
     */
    confirmBillingKey(data: ConfirmBillingKeyRequest): Promise<BillingKeyResponse>;
    /**
     * 빌링키 목록 조회
     *
     * @param customerId - 특정 고객의 빌링키만 조회 (선택)
     * @returns 빌링키 목록
     *
     * @example
     * ```typescript
     * const { billing_keys } = await client.subscription.listBillingKeys()
     * console.log(`등록된 카드: ${billing_keys.length}개`)
     * ```
     */
    listBillingKeys(customerId?: string): Promise<ListBillingKeysResponse>;
    /**
     * 빌링키 상세 조회
     *
     * @param billingKeyId - 빌링키 ID
     * @returns 빌링키 상세 정보
     */
    getBillingKey(billingKeyId: string): Promise<BillingKeyResponse>;
    /**
     * 빌링키 수정
     *
     * @param billingKeyId - 빌링키 ID
     * @param data - 수정 정보
     * @returns 수정된 빌링키 정보
     *
     * @example
     * ```typescript
     * await client.subscription.updateBillingKey(billingKeyId, {
     *     card_nickname: '주 결제 카드',
     *     is_default: true
     * })
     * ```
     */
    updateBillingKey(billingKeyId: string, data: UpdateBillingKeyRequest): Promise<BillingKeyResponse>;
    /**
     * 빌링키 삭제
     *
     * @param billingKeyId - 빌링키 ID
     */
    deleteBillingKey(billingKeyId: string): Promise<void>;
    /**
     * 구독 생성
     * 정기결제 구독을 생성합니다.
     *
     * @param data - 구독 정보
     * @returns 생성된 구독 정보
     *
     * @example
     * ```typescript
     * const subscription = await client.subscription.create({
     *     billing_key_id: 'bk_xxxxx',
     *     plan_name: '프리미엄 플랜',
     *     amount: 9900,
     *     billing_cycle: 'monthly',
     *     billing_day: 15,  // 매월 15일 결제
     *     trial_days: 7     // 7일 무료 체험
     * })
     * ```
     */
    create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
    /**
     * 구독 목록 조회
     *
     * @param params - 조회 옵션
     * @returns 구독 목록
     *
     * @example
     * ```typescript
     * const { subscriptions, total } = await client.subscription.list({
     *     status: 'active',
     *     limit: 10
     * })
     * ```
     */
    list(params?: ListSubscriptionsRequest): Promise<ListSubscriptionsResponse>;
    /**
     * 구독 상세 조회
     *
     * @param subscriptionId - 구독 ID
     * @returns 구독 상세 정보
     */
    get(subscriptionId: string): Promise<SubscriptionResponse>;
    /**
     * 구독 수정
     *
     * @param subscriptionId - 구독 ID
     * @param data - 수정 정보
     * @returns 수정된 구독 정보
     *
     * @example
     * ```typescript
     * await client.subscription.update(subscriptionId, {
     *     plan_name: '엔터프라이즈 플랜',
     *     amount: 29900
     * })
     * ```
     */
    update(subscriptionId: string, data: UpdateSubscriptionRequest): Promise<SubscriptionResponse>;
    /**
     * 구독 일시정지
     *
     * @param subscriptionId - 구독 ID
     * @param data - 일시정지 정보
     * @returns 일시정지된 구독 정보
     *
     * @example
     * ```typescript
     * await client.subscription.pause(subscriptionId, {
     *     reason: '고객 요청'
     * })
     * ```
     */
    pause(subscriptionId: string, data?: PauseSubscriptionRequest): Promise<SubscriptionResponse>;
    /**
     * 구독 재개
     *
     * @param subscriptionId - 구독 ID
     * @returns 재개된 구독 정보
     *
     * @example
     * ```typescript
     * await client.subscription.resume(subscriptionId)
     * ```
     */
    resume(subscriptionId: string): Promise<SubscriptionResponse>;
    /**
     * 구독 취소
     *
     * @param subscriptionId - 구독 ID
     * @param data - 취소 정보
     * @returns 취소된 구독 정보
     *
     * @example
     * ```typescript
     * // 현재 기간 종료 후 취소
     * await client.subscription.cancel(subscriptionId, {
     *     reason: '서비스 불만족'
     * })
     *
     * // 즉시 취소
     * await client.subscription.cancel(subscriptionId, {
     *     reason: '즉시 해지 요청',
     *     immediate: true
     * })
     * ```
     */
    cancel(subscriptionId: string, data?: CancelSubscriptionRequest): Promise<SubscriptionResponse>;
    /**
     * 요금제 스왑 (플랜 변경) — MoR(Paddle · Dodo) 구독 전용
     *
     * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
     * proration 으로 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을
     * PG 가 자동 크레딧해 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로
     * 수렴합니다.
     *
     * `proration_mode` 미지정 시 `prorated_immediately`(업그레이드 기본)가 적용됩니다.
     * 프로바이더가 지원하지 않는 정산 모드는 근사 대체 없이 400 `invalid_proration_mode` 입니다
     * (지원표는 {@link ProrationMode} 참조). 확정 전 정산액을 보여주려면 {@link previewChangePlan}
     * 을 먼저 호출하세요.
     *
     * toss/stripe/payapp/paypal 구독은 400 `plan_change_unsupported` 입니다.
     *
     * @param subscriptionId - 구독 ID
     * @param data - 새 price + 정산 옵션
     * @returns 갱신된 구독 정보
     *
     * @example
     * ```typescript
     * await client.subscription.changePlan(subscriptionId, {
     *     provider_price_ref: 'pri_family_monthly', // Dodo 는 'pdt_*'
     *     plan_name: '가족 플랜',
     *     amount: 24900,
     *     proration_mode: 'prorated_immediately',
     * })
     * ```
     */
    changePlan(subscriptionId: string, data: ChangePlanRequest): Promise<SubscriptionResponse>;
    /**
     * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle · Dodo)
     *
     * 세금·기존 크레딧 잔액까지 반영된 PG 계산값을 반환하므로, 확정 화면에
     * "지금 ₩X 청구, 이후 ₩Y/주기 (다음 청구일 …)" 를 그대로 노출하면 됩니다.
     * 직접 차액을 계산하지 마세요 — 이 값이 권위입니다.
     *
     * **금액은 반드시 짝이 되는 통화와 함께 표시하세요.** 즉시청구는 고객 표시통화
     * (`currency`), 정기 단가는 상품 통화(`recurring_currency`, 비면 `currency` 와 동일)입니다 —
     * MoR 의 adaptive currency 에서 둘이 다를 수 있습니다.
     *
     * 미리보기를 제공하지 않는 프로바이더는 400 `plan_change_preview_unsupported` 입니다.
     * 이는 **미리보기만** 없다는 뜻이며 {@link changePlan} 자체는 동작합니다
     * (요금제 변경 자체가 불가한 경우는 `plan_change_unsupported` 로 구분됩니다).
     *
     * @param subscriptionId - 구독 ID
     * @param data - 새 price + 정산 옵션 ({@link changePlan} 과 동일 body)
     * @returns 정산 미리보기 (지금 청구/크레딧 · 새 정기 청구액 · 다음 청구일)
     *
     * @example
     * ```typescript
     * const preview = await client.subscription.previewChangePlan(subscriptionId, {
     *     provider_price_ref: 'pri_family_monthly',
     * })
     * // 통화를 함께 포맷한다 — 금액만 쓰면 다통화에서 거짓 금액이 된다
     * format(preview.immediate_charge_amount, preview.currency)
     * format(preview.recurring_amount, preview.recurring_currency ?? preview.currency)
     * ```
     */
    previewChangePlan(subscriptionId: string, data: ChangePlanRequest): Promise<ChangePlanPreview>;
    /**
     * 구독 결제 이력 조회
     *
     * @param subscriptionId - 구독 ID
     * @param params - 조회 옵션
     * @returns 결제 이력 목록
     *
     * @example
     * ```typescript
     * const { payments } = await client.subscription.listPayments(subscriptionId, {
     *     limit: 10
     * })
     * ```
     */
    listPayments(subscriptionId: string, params?: ListSubscriptionPaymentsRequest): Promise<ListSubscriptionPaymentsResponse>;
    /**
     * 빌링키로 즉시 결제
     * 구독 없이 빌링키로 일회성 결제를 진행합니다.
     *
     * @param data - 결제 정보
     * @returns 결제 결과
     *
     * @example
     * ```typescript
     * const result = await client.subscription.chargeWithBillingKey({
     *     billing_key_id: 'bk_xxxxx',
     *     amount: 15000,
     *     order_name: '추가 결제'
     * })
     *
     * if (result.status === 'done') {
     *     console.log('결제 완료!')
     * }
     * ```
     */
    chargeWithBillingKey(data: ChargeWithBillingKeyRequest): Promise<ChargeWithBillingKeyResponse>;
}

/**
 * 사용자 제보 (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;
}

interface Video {
    id: string;
    channel_id: string;
    title: string;
    description?: string;
    status: VideoStatus;
    visibility: VideoVisibility;
    duration?: number;
    original_filename: string;
    original_size: number;
    qualities: VideoQuality[];
    thumbnail_url?: string;
    stream_url?: string;
    tags?: string[];
    view_count: number;
    like_count: number;
    comment_count: number;
    created_at: string;
    updated_at: string;
}
type VideoStatus = "uploading" | "processing" | "ready" | "failed";
type VideoVisibility = "public" | "private" | "unlisted" | "members_only" | "ppv";
interface VideoQuality {
    quality: string;
    width: number;
    height: number;
    bitrate: number;
    size: number;
    status: "pending" | "processing" | "ready" | "failed";
}
interface VideoListResponse {
    videos: Video[];
    total: number;
    page: number;
    limit: number;
}
interface VideoListOptions {
    status?: VideoStatus;
    visibility?: VideoVisibility;
    search?: string;
    channel_id?: string;
    page?: number;
    limit?: number;
}
interface UploadOptions {
    title: string;
    description?: string;
    visibility?: VideoVisibility;
    tags?: string[];
    channel_id?: string;
    onProgress?: (progress: UploadProgress) => void;
}
interface UploadProgress {
    phase: "uploading" | "processing" | "complete";
    uploadedChunks: number;
    totalChunks: number;
    percentage: number;
    currentSpeed?: number;
}
interface UpdateVideoRequest {
    title?: string;
    description?: string;
    visibility?: VideoVisibility;
    tags?: string[];
    thumbnail_url?: string;
}
interface StreamURLResponse {
    /** 마스터 HLS 플레이리스트 URL (적응형 비트레이트) */
    master_playlist: string;
    /** 화질 키 → 화질별 플레이리스트 URL 맵 (예: { "720p": "https://..." }) */
    qualities: Record<string, string>;
    expires_at: string;
}
interface InitUploadResponse {
    upload_id: string;
    chunk_size: number;
    total_chunks: number;
    expires_at: string;
}
interface VideoCompleteUploadResponse {
    video_id: string;
    status: VideoStatus;
}
interface TranscodeStatus {
    video_id: string;
    status: "pending" | "processing" | "completed" | "failed";
    progress: number;
    qualities: QualityProgress[];
    error?: string;
}
interface QualityProgress {
    quality: string;
    status: "pending" | "processing" | "completed" | "failed";
    progress: number;
}
interface WaitOptions {
    timeout?: number;
    interval?: number;
    onProgress?: (progress: UploadProgress) => void;
}
interface Channel {
    id: string;
    owner_id: string;
    handle: string;
    name: string;
    description?: string;
    avatar_url?: string;
    banner_url?: string;
    subscriber_count: number;
    video_count: number;
    total_views: number;
    is_verified: boolean;
    created_at: string;
    updated_at: string;
}
interface CreateChannelRequest {
    handle: string;
    name: string;
    description?: string;
}
interface UpdateChannelRequest {
    name?: string;
    description?: string;
    avatar_url?: string;
    banner_url?: string;
}
interface Playlist {
    id: string;
    channel_id: string;
    title: string;
    description?: string;
    visibility: VideoVisibility;
    thumbnail_url?: string;
    video_count: number;
    total_duration: number;
    created_at: string;
    updated_at: string;
}
interface CreatePlaylistRequest {
    title: string;
    description?: string;
    visibility?: VideoVisibility;
}
interface PlaylistItem {
    id: string;
    playlist_id: string;
    video_id: string;
    position: number;
    video?: Video;
    added_at: string;
}
interface Shorts {
    id: string;
    channel_id: string;
    video_id: string;
    title: string;
    description?: string;
    visibility: VideoVisibility;
    view_count: number;
    like_count: number;
    comment_count: number;
    share_count: number;
    is_remixable: boolean;
    original_shorts_id?: string;
    created_at: string;
}
interface ShortsListResponse {
    shorts: Shorts[];
    total: number;
    next_cursor?: string;
}
interface VideoComment {
    id: string;
    video_id: string;
    member_id: string;
    content: string;
    parent_id?: string;
    like_count: number;
    reply_count: number;
    is_pinned: boolean;
    is_hearted: boolean;
    member?: {
        id: string;
        name: string;
        avatar_url?: string;
    };
    created_at: string;
    updated_at: string;
}
interface CommentListResponse {
    comments: VideoComment[];
    total: number;
    next_cursor?: string;
}
interface WatchHistoryItem {
    id: string;
    video_id: string;
    video?: Video;
    watch_duration: number;
    completed: boolean;
    last_position: number;
    watched_at: string;
}
interface MembershipTier {
    id: string;
    channel_id: string;
    name: string;
    description?: string;
    level: number;
    price: number;
    currency: string;
    billing_period: "monthly" | "yearly";
    perks: string[];
    badge_url?: string;
    badge_color?: string;
    member_count: number;
    is_active: boolean;
}
interface ChannelMembership {
    id: string;
    channel_id: string;
    member_id: string;
    tier_id: string;
    tier?: MembershipTier;
    status: "active" | "cancelled" | "expired" | "paused";
    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;
    member_id: string;
    amount: number;
    currency: string;
    message?: string;
    color: string;
    display_duration: number;
    status: "pending" | "confirmed" | "refunded";
    member?: {
        id: string;
        name: string;
        avatar_url?: string;
    };
    created_at: string;
}
type SuperChatType = "super_chat" | "super_thanks" | "super_sticker" | "tip";
/** sendSuperChat 옵션 — videoId 또는 liveId 중 하나로 대상을 지정한다. */
interface SendSuperChatOptions {
    /** 대상 영상 ID (videoId 또는 liveId 중 하나 필수) */
    videoId?: string;
    /** 대상 라이브 ID */
    liveId?: string;
    /** 슈퍼챗 종류 (기본 'super_thanks') */
    type?: SuperChatType;
    message?: string;
    /** ISO 통화 코드 (기본 'USD') */
    currency?: string;
    stickerId?: string;
}
/**
 * 슈퍼챗 전송 응답. `client_secret` 으로 결제(Stripe PaymentIntent)를 확정해야
 * 슈퍼챗이 노출된다.
 */
interface SendSuperChatResponse {
    super_chat_id: string;
    client_secret: string;
    amount: number;
    currency: string;
    platform_fee: number;
    creator_amount: number;
    display_duration: number;
    color: string;
    highlighted: boolean;
}

declare class VideoProcessingError extends Error {
    video?: Video;
    constructor(message: string, video?: Video);
}
/**
 * Video API for uploading, streaming, and managing videos
 */
declare class VideoAPI {
    private http;
    private videoBaseUrl;
    constructor(http: HttpClient, videoBaseUrl?: string);
    private getDefaultVideoUrl;
    private getPublicPrefix;
    private videoFetch;
    /**
     * Upload a video file with chunked upload support
     */
    upload(file: File, options: UploadOptions): Promise<Video>;
    /**
     * Wait for video processing to complete
     */
    waitForReady(videoId: string, options?: WaitOptions): Promise<Video>;
    /**
     * 영상 목록 조회.
     *
     * 필터링/페이지네이션 옵션을 조합해 조건에 맞는 영상들을 반환한다.
     * 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>;
    /**
     * Get a single video
     */
    get(videoId: string): Promise<Video>;
    /**
     * Update video details
     */
    update(videoId: string, data: UpdateVideoRequest): Promise<Video>;
    /**
     * Delete a video
     */
    delete(videoId: string): Promise<void>;
    /**
     * 영상 스트리밍 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 { master_playlist, qualities, expires_at } = await cb.video.getStreamUrl(videoId)
     * videoElement.src = master_playlist // 적응형 비트레이트(HLS.js 등으로 재생)
     * // 특정 화질 고정이 필요하면 qualities['720p'] 사용
     * ```
     */
    getStreamUrl(videoId: string, quality?: string): Promise<StreamURLResponse>;
    /**
     * Get available thumbnails for a video.
     *
     * 서버는 대표 썸네일 1개(`thumbnail_url`) + 선택적 추가 썸네일 목록(`thumbnail_urls`)을
     * 반환한다. 둘을 합쳐 중복 없는 URL 배열로 정규화해 돌려준다.
     */
    getThumbnails(videoId: string): Promise<string[]>;
    /**
     * Get transcode status
     */
    getTranscodeStatus(videoId: string): Promise<TranscodeStatus>;
    /**
     * Retry failed transcoding
     */
    retryTranscode(videoId: string): Promise<void>;
    /**
     * Create a channel
     */
    createChannel(data: CreateChannelRequest): Promise<Channel>;
    /**
     * Get a channel
     */
    getChannel(channelId: string): Promise<Channel>;
    /**
     * Get channel by handle
     */
    getChannelByHandle(handle: string): Promise<Channel>;
    /**
     * Update channel
     */
    updateChannel(channelId: string, data: UpdateChannelRequest): Promise<Channel>;
    /**
     * Subscribe to a channel
     */
    subscribeChannel(channelId: string): Promise<void>;
    /**
     * Unsubscribe from a channel
     */
    unsubscribeChannel(channelId: string): Promise<void>;
    /**
     * Create a playlist for a channel.
     * 백엔드는 `POST /v1/public/playlists` 에 body 로 `channel_id` 를 받는다 (AppMember 인증).
     */
    createPlaylist(channelId: string, data: CreatePlaylistRequest): Promise<Playlist>;
    /**
     * Get a channel's public playlists.
     * 백엔드는 `GET /v1/public/playlists/public?channel_id=` 로 공개 플레이리스트를 반환한다.
     */
    getPlaylists(channelId: string): Promise<Playlist[]>;
    /**
     * Get playlist items.
     * 백엔드는 별도 items 라우트가 없고 `GET /v1/public/playlists/:id` 응답에 items 를 포함한다.
     */
    getPlaylistItems(playlistId: string): Promise<PlaylistItem[]>;
    /**
     * Add video to playlist
     */
    addToPlaylist(playlistId: string, videoId: string, position?: number): Promise<PlaylistItem>;
    /**
     * Remove video from playlist
     */
    removeFromPlaylist(playlistId: string, itemId: string): Promise<void>;
    /**
     * Get shorts feed
     */
    getShortsFeed(options?: {
        cursor?: string;
        limit?: number;
    }): Promise<ShortsListResponse>;
    /**
     * Get trending shorts
     */
    getTrendingShorts(limit?: number): Promise<ShortsListResponse>;
    /**
     * Get a single shorts
     */
    getShorts(shortsId: string): Promise<Shorts>;
    /**
     * Get comments for a video
     */
    getComments(videoId: string, options?: {
        cursor?: string;
        limit?: number;
        sort?: "recent" | "popular";
    }): Promise<CommentListResponse>;
    /**
     * Post a comment
     */
    postComment(videoId: string, content: string, parentId?: string): Promise<VideoComment>;
    /**
     * Delete a comment
     */
    deleteComment(commentId: string): Promise<void>;
    /**
     * Like a video
     */
    likeVideo(videoId: string): Promise<void>;
    /**
     * Unlike a video
     */
    unlikeVideo(videoId: string): Promise<void>;
    /**
     * Get watch history
     */
    getWatchHistory(options?: {
        cursor?: string;
        limit?: number;
    }): Promise<{
        items: WatchHistoryItem[];
        next_cursor?: string;
    }>;
    /**
     * Clear watch history
     */
    clearWatchHistory(): Promise<void>;
    /**
     * Report watch progress
     */
    reportWatchProgress(videoId: string, position: number, duration: number): Promise<void>;
    /**
     * Get membership tiers for a channel
     */
    getMembershipTiers(channelId: string): Promise<MembershipTier[]>;
    /**
     * Join a membership tier
     *
     * @param _channelId 현재 서버에서 무시됩니다 (tier 가 채널을 함의). API 안정성을 위해 시그니처만 유지.
     * @param tierId 가입할 멤버십 티어 ID
     */
    joinMembership(_channelId: string, tierId: string): Promise<ChannelMembership>;
    /**
     * Cancel membership
     *
     * @param _channelId 현재 서버에서 무시됩니다. API 안정성을 위해 시그니처만 유지.
     * @param membershipId 취소할 멤버십 ID
     */
    cancelMembership(_channelId: string, membershipId: string): Promise<void>;
    /**
     * Send a super chat to a channel.
     *
     * 백엔드는 `POST /v1/public/super-chats` 에 `channel_id`/`type`/`amount` 를 요구하고,
     * `video_id` 또는 `live_id` 중 하나로 대상을 지정한다 (AppMember 인증 필수).
     * 응답의 `client_secret` 으로 결제(Stripe)를 확정해야 슈퍼챗이 노출된다.
     *
     * @param channelId 슈퍼챗을 받을 채널 ID
     * @param amount 금액(최소 단위 정수)
     * @param options videoId 또는 liveId 중 하나로 대상 지정 + 종류/메시지/통화
     */
    sendSuperChat(channelId: string, amount: number, options?: SendSuperChatOptions): Promise<SendSuperChatResponse>;
    /**
     * Get super chats for a video
     */
    getSuperChats(videoId: string): Promise<SuperChat[]>;
    /**
     * Get recommended videos
     *
     * @deprecated Use getHomeFeed() — 동일한 개인화 피드(`/recommendations/feed`)를 반환합니다.
     */
    getRecommendations(limit?: number): Promise<Video[]>;
    /**
     * Get home feed
     */
    getHomeFeed(limit?: number): Promise<Video[]>;
    /**
     * Get related videos
     */
    getRelatedVideos(videoId: string, limit?: number): Promise<Video[]>;
    /**
     * Get trending videos
     */
    getTrendingVideos(limit?: number): Promise<Video[]>;
    /**
     * 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>;
    };
}

/**
 * WebRTC 타입 정의
 */
/** WebRTC 채널 모드 */
type WebRTCMode = "broadcast" | "interactive";
/** WebRTC 연결 상태 */
type WebRTCConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed";
/** WebRTC 연결 옵션 */
interface WebRTCConnectOptions {
    /** 룸 ID (channel:room 형식 권장) */
    roomId: string;
    /** 사용자 ID (선택) */
    userId?: string;
    /** 방송자 여부 (broadcast 모드에서 사용) */
    isBroadcaster?: boolean;
    /** 로컬 미디어 스트림 */
    localStream?: MediaStream;
}
/** 피어 정보 */
interface PeerInfo {
    /** 피어 ID */
    peer_id: string;
    /** 사용자 ID */
    user_id?: string;
    /** 방송자 여부 */
    is_broadcaster?: boolean;
    /** 참가 시간 */
    joined_at?: string;
}
/** 룸 정보 */
interface RoomInfo {
    /** 룸 ID */
    room_id: string;
    /** 채널 이름 */
    channel_name: string;
    /** 채널 타입 (broadcast/interactive) */
    channel_type: WebRTCMode;
    /** 참가자 목록 */
    peers: PeerInfo[];
}
/** 시그널링 메시지 타입 */
type SignalingMessageType = "join" | "joined" | "leave" | "offer" | "answer" | "ice_candidate" | "peer_joined" | "peer_left" | "error";
/** 시그널링 메시지 */
interface SignalingMessage {
    type: SignalingMessageType;
    room_id?: string;
    peer_id?: string;
    target_id?: string;
    sdp?: string;
    candidate?: RTCIceCandidateInit;
    data?: unknown;
}
/** ICE 서버 설정 */
interface ICEServer {
    urls: string | string[];
    username?: string;
    credential?: string;
}
/** ICE 서버 목록 응답 */
interface ICEServersResponse {
    ice_servers: ICEServer[];
}
/**
 * 채널별 통계 (룸 ID 의 `channel:room` 컨벤션 기준 집계).
 * server `GetStats` 의 `channel_stats` 맵 값과 일치.
 */
interface ChannelStats {
    rooms: number;
    peers: number;
    broadcasters: number;
    viewers: number;
}
/**
 * 룸 요약 정보 — server `GetAllRooms` (`GET /v1/apps/:appID/rooms`) 의 `rooms[]` 항목.
 * server `RoomInfo` struct 의 JSON 와이어 형태와 정확히 일치한다.
 */
interface RoomSummary {
    id: string;
    app_id: string;
    peer_count: number;
    broadcaster_count: number;
    viewer_count: number;
}
/**
 * 앱 통계 응답 — server `GetStats` (`GET /v1/apps/:appID/stats`) 의 와이어 형태.
 * `channel_stats` 는 채널명 → ChannelStats 맵.
 */
interface AppStatsResponse {
    room_count: number;
    total_peers: number;
    total_broadcasters: number;
    total_viewers: number;
    channel_stats: Record<string, ChannelStats>;
}
/** 룸 목록 응답 — server `GetAllRooms` 가 `{ rooms: RoomSummary[] }` 로 반환. */
interface RoomsResponse {
    rooms: RoomSummary[];
}
/** API 유효성 검증 응답 */
interface ValidateResponse {
    valid: boolean;
    app_id: string;
}
/** 참가 요청 */
interface JoinRoomRequest {
    room_id: string;
    user_id?: string;
    is_broadcaster?: boolean;
}
/** 참가 응답 */
interface JoinRoomResponse {
    peer_id: string;
    room_id: string;
    channel_name: string;
    channel_type: WebRTCMode;
    peers: PeerInfo[];
}

/**
 * WebRTC API
 * 실시간 영상/음성 통화 (Pion WebRTC 기반)
 */
declare class WebRTCAPI {
    private http;
    private webrtcUrl;
    private appId?;
    private ws;
    private state;
    private stateListeners;
    private errorListeners;
    private peerJoinedListeners;
    private peerLeftListeners;
    private remoteStreamListeners;
    private reconnectAttempts;
    private maxReconnectAttempts;
    private reconnectTimeout;
    private currentRoomId;
    private currentPeerId;
    private currentUserId;
    private isBroadcaster;
    private localStream;
    private channelType;
    private peerConnections;
    private remoteStreams;
    private iceServers;
    constructor(http: HttpClient, webrtcUrl: string, appId?: string);
    /**
     * ICE 서버 목록 조회
     */
    getICEServers(): Promise<ICEServer[]>;
    /**
     * WebRTC 시그널링 서버에 연결
     *
     * @example
     * ```typescript
     * // 로컬 스트림 가져오기
     * const localStream = await navigator.mediaDevices.getUserMedia({
     *     video: true,
     *     audio: true
     * })
     *
     * // WebRTC 연결
     * await cb.webrtc.connect({
     *     roomId: 'live:room-123',
     *     userId: 'user-456',
     *     isBroadcaster: true,
     *     localStream
     * })
     * ```
     */
    connect(options: WebRTCConnectOptions): Promise<void>;
    private connectWebSocket;
    private buildWebSocketUrl;
    private handleSignalingMessage;
    private createPeerConnection;
    private handleOffer;
    private handleAnswer;
    private handleICECandidate;
    private closePeerConnection;
    private sendSignaling;
    private handleDisconnect;
    private attemptReconnect;
    /**
     * WebRTC 연결 해제
     */
    disconnect(): void;
    /**
     * 현재 연결 상태 조회
     */
    getState(): WebRTCConnectionState;
    /**
     * 현재 룸 ID 조회
     */
    getRoomId(): string | null;
    /**
     * 현재 피어 ID 조회
     */
    getPeerId(): string | null;
    /**
     * 현재 채널 타입 조회
     */
    getChannelType(): WebRTCMode;
    /**
     * 원격 스트림 조회
     */
    getRemoteStream(peerId: string): MediaStream | undefined;
    /**
     * 모든 원격 스트림 조회
     */
    getAllRemoteStreams(): Map<string, MediaStream>;
    /**
     * 로컬 스트림 교체
     */
    replaceLocalStream(newStream: MediaStream): void;
    /**
     * 오디오 음소거/해제
     */
    setAudioEnabled(enabled: boolean): void;
    /**
     * 비디오 켜기/끄기
     */
    setVideoEnabled(enabled: boolean): void;
    /**
     * 연결 상태 변경 이벤트
     */
    onStateChange(callback: (state: WebRTCConnectionState) => void): () => void;
    /**
     * 에러 이벤트
     */
    onError(callback: (error: Error) => void): () => void;
    /**
     * 피어 참가 이벤트
     */
    onPeerJoined(callback: (peerId: string, info: PeerInfo) => void): () => void;
    /**
     * 피어 퇴장 이벤트
     */
    onPeerLeft(callback: (peerId: string) => void): () => void;
    /**
     * 원격 스트림 수신 이벤트
     */
    onRemoteStream(callback: (peerId: string, stream: MediaStream) => void): () => void;
    private setState;
    private emitError;
    private emitPeerJoined;
    private emitPeerLeft;
    private emitRemoteStream;
    /**
     * API Key 또는 JWT 토큰 유효성 검증
     *
     * 연결 전 인증 정보가 올바른지 사전 확인할 때 사용합니다.
     *
     * @example
     * ```typescript
     * const result = await cb.webrtc.validate()
     * if (result.valid) {
     *     console.log('인증 성공, appId:', result.app_id)
     *     await cb.webrtc.connect({ roomId: 'channel:room' })
     * }
     * ```
     */
    validate(): Promise<ValidateResponse>;
    /**
     * 앱의 WebRTC 통계 조회
     */
    getStats(appID: string): Promise<AppStatsResponse>;
    /**
     * 앱의 활성 룸 목록 조회
     */
    getRooms(appID: string): Promise<RoomsResponse>;
}

/**
 * WebTransport-based Game Client
 *
 * WebTransport provides lower latency than WebSocket by using:
 * - UDP-based QUIC protocol
 * - Unreliable datagrams for real-time game state
 * - Reliable streams for critical messages
 *
 * Falls back to WebSocket if WebTransport is not supported.
 */

/**
 * Transport type for game connection
 */
type TransportType = "webtransport" | "websocket" | "auto";
/**
 * Extended game client config with transport options
 */
interface GameTransportConfig extends GameClientConfig {
    /** Preferred transport type */
    transport?: TransportType;
    /** Use unreliable datagrams for state updates (WebTransport only) */
    useUnreliableDatagrams?: boolean;
    /** Maximum datagram size (WebTransport only) */
    maxDatagramSize?: number;
}
/**
 * Check if WebTransport is available
 */
declare function isWebTransportSupported(): boolean;
/**
 * GameRoomTransport - Game room client with WebTransport support
 *
 * Provides the same API as GameRoom but with WebTransport support for
 * lower latency game state synchronization.
 */
declare class GameRoomTransport {
    private transport;
    private config;
    private handlers;
    private reconnectAttempts;
    private reconnectTimer;
    private pingInterval;
    private actionSequence;
    private _roomId;
    private _state;
    private _scriptName;
    private _scriptVersion;
    private _isConnected;
    private _connectionStatus;
    private _lastError;
    private _latency;
    private _transportType;
    private decoder;
    private pendingHandlers;
    private messageId;
    constructor(config: GameTransportConfig);
    private getDefaultGameServerUrl;
    /**
     * Current transport type being used
     */
    get transportType(): TransportType;
    /**
     * Current room ID
     */
    get roomId(): string | null;
    /**
     * Current game state
     */
    get state(): GameState | null;
    /**
     * 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
     */
    get connectionState(): GameConnectionState;
    /**
     * Current latency (ms)
     */
    get latency(): number;
    /**
     * Register event handler
     */
    on<K extends keyof GameEventHandlers>(event: K, handler: GameEventHandlers[K]): this;
    /**
     * Connect to game server
     */
    connect(roomId?: string): Promise<void>;
    /**
     * Disconnect from server
     */
    disconnect(): void;
    /**
     * 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
     */
    joinRoom(roomId: string, metadata?: Record<string, string>): Promise<GameState>;
    /**
     * Leave current room
     */
    leaveRoom(): Promise<void>;
    /**
     * Send game action
     * Uses unreliable transport (datagrams) when WebTransport is available
     */
    sendAction(action: GameAction, reliable?: boolean): void;
    /**
     * Send chat message
     */
    sendChat(message: string): void;
    /**
     * Request current state
     */
    requestState(): Promise<GameState>;
    /**
     * Ping server for latency measurement
     */
    ping(): Promise<number>;
    private send;
    private sendWithHandler;
    private handleMessage;
    private handleDelta;
    private applyChange;
    private handlePlayerEvent;
    private scheduleReconnect;
    private startPingInterval;
    private stopPingInterval;
}

interface ConnectBaseConfig {
    /**
     * Connect Base API 서버 URL (선택사항)
     * @default 'https://api.connectbase.world'
     * @example 'https://api.connectbase.world'
     */
    baseUrl?: string;
    /**
     * Connect Base Socket 서버 URL (선택사항, 실시간 통신용)
     * @default 'https://socket.connectbase.world'
     * @example 'https://socket.connectbase.world'
     */
    socketUrl?: string;
    /**
     * Connect Base WebRTC 서버 URL (선택사항, 영상/음성 통화용)
     * @default 'https://webrtc.connectbase.world'
     * @example 'https://webrtc.connectbase.world'
     */
    webrtcUrl?: string;
    /**
     * Connect Base Video 서버 URL (선택사항, 동영상 업로드/스트리밍용)
     * @default 'https://video.connectbase.world'
     * @example 'https://video.connectbase.world'
     */
    videoUrl?: string;
    /**
     * Connect Base Game 서버 URL (선택사항, 실시간 멀티플레이어 게임용)
     * @default 'https://game.connectbase.world'
     * @example 'https://game.connectbase.world'
     */
    gameUrl?: string;
    /**
     * 앱 ID (콘솔에서 확인, WebRTC 등 일부 기능에 필요)
     */
    appId?: string;
    /**
     * 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 인증에
     * 사용됩니다. 서버 환경에서만 사용하고 절대 브라우저에 노출하지 마세요.
     */
    secretKey?: string;
    /**
     * 토큰이 갱신될 때 호출되는 콜백
     */
    onTokenRefresh?: (tokens: {
        accessToken: string;
        refreshToken: string;
    }) => void;
    /**
     * 인증 에러 발생 시 호출되는 콜백
     */
    onAuthError?: (error: Error) => void;
    /**
     * 토큰이 만료되어 갱신에 실패했을 때 호출되는 콜백
     * 리프레시 토큰도 만료되어 재로그인이 필요한 상황에서 호출됩니다.
     * @example
     * ```typescript
     * const cb = new ConnectBase({
     *     publicKey: 'your-public-key',
     *     onTokenExpired: () => {
     *         // 로그인 페이지로 리다이렉트
     *         window.location.href = '/login'
     *     }
     * })
     * ```
     */
    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
 *
 * @example
 * ```typescript
 * import ConnectBase from 'connectbase-client'
 *
 * // 간단 초기화 (API Key만 필요)
 * const cb = new ConnectBase({
 *     publicKey: 'your-public-key'
 * })
 *
 * // 커스텀 서버 URL 사용 시
 * const cb = new ConnectBase({
 *     baseUrl: 'https://your-server.com',
 *     publicKey: 'your-public-key'
 * })
 *
 * // 데이터 조회
 * const data = await cb.database.getData('table-id')
 *
 * // 파일 업로드
 * const file = await cb.storage.uploadFile('storage-id', myFile)
 *
 * // 서버리스 함수 실행
 * const result = await cb.functions.invoke('function-id', { name: 'John' })
 *
 * // 실시간 통신 (채팅 등)
 * await cb.realtime.connect()
 * const chat = await cb.realtime.subscribe('chat-room-1')
 * chat.onMessage((msg) => console.log(msg))
 * await chat.send({ text: 'Hello!' })
 * ```
 */
declare class ConnectBase {
    private http;
    /**
     * 인증 API
     */
    readonly auth: AuthAPI;
    /**
     * 데이터베이스 API
     */
    readonly database: DatabaseAPI;
    /**
     * 스토리지 API
     */
    readonly storage: StorageAPI;
    /**
     * Public Key 관리 API
     */
    readonly publicKey: PublicKeyAPI;
    /**
    /**
     * 서버리스 함수 API
     */
    readonly functions: FunctionsAPI;
    /**
     * 실시간 통신 API (WebSocket)
     */
    readonly realtime: RealtimeAPI;
    /**
     * WebRTC API (영상/음성 통화)
     */
    readonly webrtc: WebRTCAPI;
    /**
     * 에러 트래커 API (클라이언트 에러 리포팅)
     */
    readonly errorTracker: ErrorTrackerAPI;
    /**
     * OAuth API (소셜 로그인)
     */
    readonly oauth: OAuthAPI;
    /**
     * 결제 API (토스페이먼츠)
     */
    readonly payment: PaymentAPI;
    /**
     * 정기결제/구독 API
     */
    readonly subscription: SubscriptionAPI;
    /**
     * 푸시 알림 API
     */
    readonly push: PushAPI;
    /**
     * 앱 역할(RBAC) 관리 API — 서버사이드 전용(ctx.cbAdmin / 콘솔 JWT).
     * service_role 함수에서는 management_scopes(role:read / role:manage)가 필요하다.
     */
    readonly roles: RolesAPI;
    /**
     * 비디오 API (동영상 업로드/스트리밍)
     */
    readonly video: VideoAPI;
    /**
     * 게임 API (실시간 멀티플레이어)
     */
    readonly game: GameAPI;
    /**
     * 광고 API (Google AdSense)
     */
    readonly ads: AdsAPI;
    /**
     * 네이티브 브릿지 API (크로스 플랫폼)
     * 웹, 모바일(React Native), 데스크톱(Electron)에서 동일한 API로 네이티브 기능 사용
     */
    readonly native: NativeAPI;
    /**
     * 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;
    /**
     * 현재 페이지가 토큰-in-URL OAuth 리다이렉트 콜백(팝업 아님)인지 판별.
     *
     * `?access_token=&refresh_token=` 이 있고 `window.opener` 가 없으면 true — 부팅 안전망
     * (`oauth.consumeRedirectCallbackOnBoot`)으로 토큰을 자동 소비할 대상이다. 팝업 콜백
     * (`window.opener` 존재)은 `getCallbackResult()` 의 postMessage 경로가 전담하므로 제외한다.
     * code-only(`?code=`)·에러(`?error=`) 콜백도 제외(네트워크 교환/에러 분기는 앱이 명시 호출).
     */
    private isOAuthRedirectCallbackUrl;
    /**
     * 새로고침/탭 재개 후 cookie 만으로 세션을 복원한다 (브라우저 전용).
     *
     * 일반적으로는 ConnectBase 생성 시 `autoRestoreSession: true` (기본값) 으로 자동 호출되지만,
     * 호출 결과를 await 해서 로그인 상태에 따라 다른 UI 를 그리고 싶다면 명시적으로 호출한다.
     *
     * @returns access token 복원 성공 시 true, 미로그인/cookie 만료 시 false
     */
    restoreSession(): Promise<boolean>;
    /**
     * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)
     */
    setTokens(accessToken: string, refreshToken: string): void;
    /**
     * 토큰 제거
     */
    clearTokens(): void;
    /**
     * 설정 업데이트
     */
    updateConfig(config: Partial<ConnectBaseConfig>): void;
}

export { AIAPI, type AIChatRequest, type AIChatResponse, type AIChatStreamCallbacks, type AIChatStreamOptions, 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 ChangePlanPreview, type ChangePlanRequest, type Channel, type ChannelMembership, type ChannelStats, 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 CreateRolePayload, type CreateRoleResult, 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 GeoBoundingBox, type GeoIndex, type GeoNear, type GeoPoint, type GeoPolygon, type GeoQuery, type GeoResponse, type GeoResult, type GetAuthorizationURLResponse, type GetFileByPathResponse, type GoogleConnectionStatus, 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 ListPaymentsOptions, 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 OnPaymentFailure, type OpenDialogOptions, type OpenDialogResult, type PageMetaResponse, type PartyInfo, type PartyInvite, type PartyMember, type PauseSubscriptionRequest, type PaymentDetail, type PaymentListItem, type PaymentListResult, type PaymentMode, 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 ProrationMode, type PublicKeyItem, type PublicKeyPaymentMode, type PublishBatchRequest, type PublishBatchResponse, type PublishMessageRequest, type PublishMessageResponse, type PushPlatform, type PushStatsResult, 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 RoleDetail, type RoleList, type RoleListItem, type RolePermissionItem, type RoleUserItem, RolesAPI, type RoomInfo, type RoomStaleMessage, type RoomSummary, 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 SendSuperChatOptions, type SendSuperChatResponse, type ServerMessage, SessionManager, type SetPageMetaRequest, type Shorts, type ShortsListResponse, type SignalingMessage, type SignalingMessageType, type SlowQueryInfo, type SpectatorInfo, type SpectatorPlayerState, type SpectatorState, type SpeechRecognizeOptions, type SpeechResult, type StateChange, type StateChangeHandler, type StorageUploadOptions, type StorageUploadProgress, 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 SuperChatType, 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 UpdateRolePayload, type UpdateSecurityRuleRequest, type UpdateSubscriptionRequest, type UpdateTriggerRequest, type UpdateVideoRequest, type UpdateVideoStorageRequest, type UploadByPathOptions, type UploadFileOptions, type UploadFileResponse, type UploadOptions, type UploadProgress, type VAPIDPublicKeyResponse, type ValidateResponse, type ValidationSchema, type ValidationSchemaField, type ValidationStateTransitions, type Video, type VideoComment, type VideoCompleteUploadResponse, 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 };