connectbase-client 6.10.0 → 6.11.0

package/dist/index.d.ts

@@ -428,6 +428,11 @@ declare class HttpClient {
     getRecentCalls(): RecentApiCall[];
     /** 최근 호출 buffer clear (테스트/프라이버시 처리). */
     clearRecentCalls(): void;
+    /**
+     * Secret Key 는 계정 권한의 자격증명이다. 브라우저 번들에 넣으면 페이지를 여는 누구나 읽는다.
+     * 막지는 않는다(Electron 등 신뢰된 환경이 있다) — 대신 무엇이 위험한지 분명히 알린다.
+     */
+    private warnIfSecretKeyInBrowser;
     private warnIfUnsafePersistence;
     updateConfig(config: Partial<HttpClientConfig>): void;
     setTokens(accessToken: string, refreshToken: string): void;
@@ -3342,6 +3347,8 @@ declare class DatabaseAPI {
      * `options.autoCreate: true` 시 테이블이 없으면 빈 schemaless 테이블을
      * 자동으로 생성한 뒤 insert. opt-in 이며 프로토타입/AI 자동화 워크플로에
      * 권장합니다. production 앱은 명시적 `createTable` 호출 권장.
+     * 테이블 생성은 `secretKey` 나 service_role 함수에서만 됩니다. Public Key 만으로는
+     * 옵션이 무시되어, 없는 테이블이면 404 입니다 (이미 있는 테이블에는 그대로 씁니다).
      */
     createData(tableIdOrName: string, data: CreateDataRequest, options?: {
         autoCreate?: boolean;
@@ -3533,13 +3540,13 @@ declare class DatabaseAPI {
      * // 자기 앱 테이블 구독 (AppMember JWT)
      * cb.database.connectRealtime({
      *     accessToken: 'your-jwt-token',
-     *     dataServerUrl: 'https://data.connectbase.world'
+     *     dataServerUrl: 'https://api.connectbase.world'
      * })
      *
      * // cross-app: Provider 앱의 테이블 구독 (OAuth access token)
      * cb.database.connectRealtime({
      *     accessToken: oauthAccessToken,
-     *     dataServerUrl: 'https://data.connectbase.world'
+     *     dataServerUrl: 'https://api.connectbase.world'
      * })
      *
      * // 테이블 구독
@@ -5326,11 +5333,11 @@ type KnowledgeFileInput = File | Blob | {
  *
  * 접근 범위는 세 축으로 판정됩니다 (2026-09-06 fail-closed 전환).
  *
- * 1. **익명 (퍼블릭 키만)** — `metadata.user_id` 가 **없는** 문서만 조회/검색/수정/삭제.
- *    FAQ 나 제품 문서 같은 공유 코퍼스는 종전과 동일하게 동작합니다.
+ * 1. **익명 (퍼블릭 키만)** — `metadata.user_id` 가 **없는** 문서의 조회/검색만.
+ *    문서 추가, 수정, 삭제는 401 `KB_WRITE_CREDENTIAL_REQUIRED` 입니다 (2026-11-08 부터).
  * 2. **회원 (`Authorization: Bearer <appmember-jwt>` 동봉)** — 본인 문서만. addDocument 시
  *    `metadata.user_id` 가 자동 태깅되고, 클라이언트가 다른 값을 넣어도 서버가 덮어씁니다.
- * 3. **관리자 (`secretKey: 'cb_sk_*'`)** — 전체 접근. 서버사이드 동기화/대리 색인용.
+ * 3. **관리자 (`secretKey: 'cb_sk_*'`)** — 전체 접근. 공유 문서 관리, 서버사이드 동기화/대리 색인용.
  *
  * 퍼블릭 키만으로 `metadata.user_id` 를 직접 지정하면 403 `MEMBER_SCOPED_METADATA_DENIED`,
  * 회원 귀속 문서를 건드리면 403 `CROSS_USER_ACCESS_DENIED` 입니다. 퍼블릭 키는 브라우저 번들에
@@ -5340,7 +5347,7 @@ type KnowledgeFileInput = File | Blob | {
  * ```typescript
  * const cb = new ConnectBase({ publicKey: 'your-public-key' })
  *
- * // 텍스트 문서 추가
+ * // 텍스트 문서 추가 (로그인한 회원 토큰이나 secretKey 가 있어야 한다)
  * await cb.knowledge.addDocument('kb-id', {
  *     name: '환불 정책',
  *     source_type: 'text',
@@ -5376,6 +5383,7 @@ declare class KnowledgeAPI {
      * 문서 추가
      *
      * 지식 베이스에 새 문서를 추가합니다. 텍스트 소스인 경우 즉시 처리됩니다.
+     * 로그인한 회원 토큰(본인 문서)이나 `secretKey` 가 필요합니다. Public Key 만으로는 401 입니다.
      *
      * @param kbID - 지식 베이스 ID
      * @param data - 문서 생성 요청
@@ -5505,6 +5513,7 @@ declare class KnowledgeAPI {
      * 문서 삭제
      *
      * 문서와 관련된 모든 청크도 함께 삭제됩니다.
+     * 로그인한 회원 토큰(본인 문서)이나 `secretKey` 가 필요합니다. Public Key 만으로는 401 입니다.
      *
      * @param kbID - 지식 베이스 ID
      * @param docID - 문서 ID
@@ -6286,6 +6295,15 @@ interface OAuthCallbackResponse {
     email?: string;
 }
 
+/** `exchangeCodeFromCallback()` 의 결과. */
+interface ExchangedCallbackResult {
+    access_token: string;
+    refresh_token: string;
+    member_id: string;
+    is_new_member: boolean;
+    email?: string;
+    state?: string;
+}
 /**
  * 3rd-party 인앱 브라우저(카카오톡, 라인, 인스타그램, 페이스북 등) 감지
  * 구글은 이런 환경에서 OAuth를 차단(disallowed_useragent)하므로 별도 처리 필요
@@ -6313,6 +6331,10 @@ declare class OAuthAPI {
      * 발화하지 않도록 이 promise 를 공유한다 (이중 re-issue/rotation 방지).
      */
     private bootConsumePromise;
+    /** 이 인스턴스가 `getCallbackResult()` 로 이미 적재한 콜백. 다시 불려도 토큰을 되돌리지 않는다. */
+    private loadedCallback;
+    /** 진행 중이거나 끝난 code 교환. 주소에서 code 를 지운 뒤의 재호출이 같은 결과를 받게 한다. */
+    private codeExchange;
     constructor(http: HttpClient);
     /**
      * 활성화된 OAuth 프로바이더 목록 조회
@@ -6338,7 +6360,8 @@ declare class OAuthAPI {
      *
      * @param provider - OAuth 프로바이더 (google, naver, github, discord)
      * @param callbackUrl - OAuth 완료 후 리다이렉트될 앱의 URL
-     * @param state - 선택적 state 파라미터 (CSRF 방지 등)
+     * @param state - 앱이 콜백까지 들고 가고 싶은 값(선택). `getCallbackResult()` 결과의 `state` 로 돌아온다.
+     *   로그인 CSRF 방어는 SDK 가 별도의 일회용 값으로 항상 수행하므로 이 값이 없어도 안전하다.
      * @param options - `createIfNotExists: true` 면 미가입 사용자를 자동 가입시킨다([signUp] 과 동일 동작).
      *
      * @example
@@ -6371,6 +6394,28 @@ declare class OAuthAPI {
      */
     signUp(provider: OAuthProvider, callbackUrl: string, state?: string): Promise<void>;
     private startCentralOAuth;
+    /**
+     * 콜백에서 확인할 일회용 state 를 만들어 이 브라우저에 저장합니다.
+     *
+     * `signIn()` / `signUp()` 은 이미 내부에서 부르므로 호출할 필요가 없습니다. 인가 주소를 SDK 밖에서
+     * 만드는 앱(`GET /v1/public/oauth/:provider/authorize/central` 직접 호출 등)만, 돌려받은 값을 `state`
+     * 쿼리로 넘기세요. 이 값 없이 돌아온 콜백의 토큰은 남이 보낸 링크와 구분할 수 없어 거부됩니다.
+     *
+     * @param appState - 콜백까지 들고 갈 앱의 값(선택). 서버로 보내지 않고 `getCallbackResult()` 의 `state` 로 돌아옵니다.
+     * @returns 인가 요청의 `state` 쿼리에 넣을 값
+     * @throws 브라우저 저장소를 쓸 수 없을 때
+     *
+     * @example
+     * ```typescript
+     * const state = cb.oauth.createCallbackState()
+     * const res = await fetch(`${API}/v1/public/oauth/google/authorize/central?app_callback=${callback}&state=${state}`, {
+     *     headers: { 'X-Public-Key': PUBLIC_KEY },
+     * })
+     * ```
+     */
+    createCallbackState(appState?: string): string;
+    /** 콜백 주소가 다른 출처면 그쪽 저장소에는 state 가 없어 콜백에서 거부된다는 점을 시작할 때 알린다. */
+    private createCallbackStateFor;
     /**
      * 소셜 로그인 (팝업 방식)
      * 팝업 창에서 소셜 로그인을 처리하고 결과를 Promise로 반환합니다.
@@ -6383,6 +6428,7 @@ declare class OAuthAPI {
      *
      * @param provider - OAuth 프로바이더
      * @param callbackUrl - (선택) OAuth 완료 후 리다이렉트될 팝업의 URL. 미지정 시 서버 제공 콜백 사용.
+     *   지정한다면 이 메서드를 부르는 페이지와 같은 출처여야 합니다(콜백 페이지는 토큰을 같은 출처 창에만 넘깁니다).
      * @returns 로그인 결과
      *
      * @example
@@ -6398,6 +6444,18 @@ declare class OAuthAPI {
     signInWithPopup(provider: OAuthProvider, callbackUrl?: string, options?: {
         intent?: "signin" | "signup";
     }): Promise<OAuthCallbackResponse>;
+    /**
+     * 팝업 메시지를 보낼 수 있는 출처: 서버 제공 콜백 페이지(API 서버)와 앱이 지정한 콜백 페이지.
+     *
+     * 서버 제공 콜백의 출처는 `baseUrl` 과 다를 수 있어(`/cb-api` 패스스루) 서버가 정한 redirect_uri 도
+     * 함께 본다. 인가 주소는 우리 API 응답이므로 믿을 수 있다.
+     */
+    private popupMessageOrigins;
+    /**
+     * 팝업 메시지에서 로그인 결과를 만든다. code 가 있으면 교환한다(opener_origin 을 보낸 요청의 기본 응답).
+     * 토큰을 직접 싣는 메시지는 opener_origin 을 모르는 구버전 서버 호환이다.
+     */
+    private readPopupResult;
     /**
      * 콜백 URL에서 OAuth 결과 추출
      * 중앙 콜백 방식에서 리다이렉트 후 URL 파라미터에서 결과를 추출합니다.
@@ -6413,6 +6471,10 @@ declare class OAuthAPI {
      * 없는 상태로 `getMe()` 가 401 으로 떨어지는 회귀가 있었다 (platform-issue
      * 019e638d, 2026-05-26).
      *
+     * 토큰은 이 브라우저에서 `signIn()` / `signUp()` 으로 시작한 로그인의 결과일 때만 받아들입니다. 확인되지
+     * 않으면(남이 보낸 링크 등) 토큰을 적재하지 않고 `{ error: 'oauth_state_mismatch' }` 를 돌려줍니다.
+     * 토큰은 SDK 가 생성될 때 주소에서 지우므로 `location.search` 로 직접 읽을 수 없습니다.
+     *
      * @returns OAuth 결과 (토큰, member_id 등) 또는 null
      *
      * @example
@@ -6437,6 +6499,17 @@ declare class OAuthAPI {
         state?: string;
         error?: string;
     } | null>;
+    /**
+     * 콜백 토큰을 이 인스턴스에 한 번만 적재한다. 앱이 `getCallbackResult()` 를 다시 불러도 그사이 회전된
+     * 토큰을 콜백의 옛 토큰으로 되돌리지 않는다.
+     */
+    private loadCallbackOnce;
+    /**
+     * (SDK 내부용 — `ConnectBase` 생성자가 호출) 주소의 토큰 콜백을 회수해 지우고 그 종류를 알린다.
+     *
+     * @returns `redirect` 면 부팅 안전망 대상, `popup` 이면 팝업 콜백, `none` 이면 토큰 콜백이 아니거나 거부됨.
+     */
+    captureCallbackOnBoot(): "redirect" | "popup" | "none";
     /**
      * (SDK 내부용 — `ConnectBase` 생성자가 호출) 부팅 안전망.
      *
@@ -6450,10 +6523,9 @@ declare class OAuthAPI {
      * 이 안전망은 콜백 처리 코드를 빠뜨린 앱도 동작하게 한다.
      *
      * **token rotation race(2026-05-16) 가 없는 이유:** 사전 `re-issue`(cookie 복구) 없이 URL
-     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업
-     * (`window.opener` 존재)은 `ConnectBase` 생성자에서 제외되어 호출되지 않는다 (팝업 콜백은
-     * `getCallbackResult()` 의 postMessage 경로 전담). code-only(`?code=`)·에러(`?error=`)
-     * 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
+     * 토큰을 *직접* 소비한다 — `getCallbackResult()` 의 리다이렉트 경로와 동일한 동작이다. 팝업 콜백과
+     * 거부된 콜백(`captureCallbackOnBoot()` 참고)은 생성자에서 제외되어 호출되지 않는다. code-only(`?code=`),
+     * 에러(`?error=`) 콜백도 생성자에서 제외된다 (네트워크 교환/에러 분기는 앱이 명시 호출).
      *
      * @returns 토큰 적재 성공 시 true, no-op(토큰 없음 등)이면 false.
      */
@@ -6469,20 +6541,17 @@ declare class OAuthAPI {
      *   1) `cb.oauth.exchangeCodeFromCallback()` 먼저 — code-only 모드면 성공
      *   2) null 반환 시 `cb.oauth.getCallbackResult()` 폴백 (legacy 토큰-in-URL 모드)
      *
+     * `getCallbackResult()` 와 같은 이유로, 이 브라우저에서 시작한 로그인의 `code` 만 교환합니다. 확인되지
+     * 않으면 `oauth_state_mismatch` 오류를 던지고 교환하지 않습니다.
+     *
      * @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>;
+    exchangeCodeFromCallback(): Promise<ExchangedCallbackResult | null>;
+    private exchangeCode;
 }
 
 /**
@@ -7155,6 +7224,9 @@ declare class PaymentAPI {
      * 결제 취소
      * 완료된 결제를 취소합니다. 부분 취소도 가능합니다.
      *
+     * **서버 전용.** 환불은 돈이 나가는 동작이라 `secretKey`(`cb_sk_*`, `app:update` 권한)가 필요합니다.
+     * 브라우저에서 Public Key 만으로 호출하면 401 `SECRET_KEY_REQUIRED` 입니다.
+     *
      * @param paymentId - 결제 ID (Connect Base에서 발급한 ID)
      * @param data - 취소 정보 (사유, 부분 취소 금액)
      * @returns 취소된 결제 정보
@@ -7178,6 +7250,10 @@ declare class PaymentAPI {
      * 주문 ID로 결제 조회
      * 특정 주문의 결제 상태를 조회합니다.
      *
+     * Public Key 만으로 호출하면 상태와 금액만 돌려줍니다. `customer_email`, `customer_name`, `customer_id`, `receipt_url`,
+     * `metadata`, `country`, `settlement_*`, `cancel_reason` 은 그 결제의 회원 본인(로그인 상태), `secretKey`(`app:read` 권한),
+     * 또는 `payment:read` 스코프의 service_role 함수에만 옵니다.
+     *
      * @param orderId - 주문 ID
      * @returns 결제 상세 정보
      *
@@ -11288,9 +11364,14 @@ type WebRTCConnectionState = "disconnected" | "connecting" | "connected" | "reco
 interface WebRTCConnectOptions {
     /** 룸 ID (channel:room 형식 권장) */
     roomId: string;
-    /** 사용자 ID (선택) */
+    /**
+     * SDK 로컬 값이다. 서버는 쓰지 않는다 — 참가자의 `user_id` 는 로그인 멤버 ID, 익명 연결은 빈 문자열이다.
+     */
     userId?: string;
-    /** 방송자 여부 (broadcast 모드에서 사용) */
+    /**
+     * broadcast 채널의 방송자 요청. 실제 역할은 서버가 정한다 — 로그인 멤버(accessToken) 연결만 방송자가 되고,
+     * 익명(공개 키) 연결은 시청자로 참가한다. 미디어 송수신은 이 값과 무관하게 된다.
+     */
     isBroadcaster?: boolean;
     /** 로컬 미디어 스트림 */
     localStream?: MediaStream;
@@ -11318,7 +11399,7 @@ interface RoomInfo {
     peers: PeerInfo[];
 }
 /** 시그널링 메시지 타입 */
-type SignalingMessageType = "join" | "joined" | "leave" | "offer" | "answer" | "ice_candidate" | "peer_joined" | "peer_left" | "error";
+type SignalingMessageType = "join" | "joined" | "warning" | "leave" | "offer" | "answer" | "ice_candidate" | "peer_joined" | "peer_left" | "error";
 /** 시그널링 메시지 */
 interface SignalingMessage {
     type: SignalingMessageType;
@@ -11391,16 +11472,22 @@ interface ValidateResponse {
 /** 참가 요청 */
 interface JoinRoomRequest {
     room_id: string;
-    user_id?: string;
+    /** 방송자 요청. 서버가 정한다(`JoinRoomResponse.is_broadcaster`). */
     is_broadcaster?: boolean;
 }
-/** 참가 응답 */
+/** 참가 응답 (`POST /rooms/join`) */
 interface JoinRoomResponse {
     peer_id: string;
-    room_id: string;
-    channel_name: string;
-    channel_type: WebRTCMode;
+    /** 이 피어의 소유 증명. offer / ice-candidate / leave 에 함께 보낸다. */
+    peer_token: string;
     peers: PeerInfo[];
+    /** 서버가 정한 역할 */
+    is_broadcaster: boolean;
+    /** 참가는 됐지만 요청대로 되지 않은 사항 (예: `broadcaster_requires_auth`) */
+    warning?: {
+        code: string;
+        message: string;
+    };
 }
 
 /**
@@ -12050,22 +12137,13 @@ declare class ConnectBase {
     readonly support: SupportAPI;
     constructor(config?: ConnectBaseConfig);
     /**
-     * 현재 페이지가 OAuth 리다이렉트 콜백 페이지인지 판별.
+     * 현재 페이지가 앱이 직접 처리할 OAuth 콜백 페이지인지 판별.
      *
-     * `?access_token=...&refresh_token=...` (legacy 토큰-in-URL 흐름) 또는
-     * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`)
-     * 패턴이면 true. 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다.
+     * `?code=...` (OAUTH_CODE_ONLY 흐름) 또는 OAuth 에러 응답 (`?error=...&state=...`) 패턴이면 true.
+     * 콜백 페이지에서 일반 `autoRestoreSession` 을 건너뛰어 rotation race 를 피한다. 토큰 콜백은
+     * 이미 주소에서 회수됐으므로 여기서 보지 않는다(`oauth.captureCallbackOnBoot`).
      */
     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 만으로 세션을 복원한다 (브라우저 전용).
      *