connectbase-client 3.18.0 → 3.20.0

package/dist/index.d.mts

@@ -6952,24 +6952,33 @@ interface CreateDocumentRequest {
      * 비어있으면 서버가 매직 바이트로 자동 추정 — 정확도를 위해 명시 권장.
      */
     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` 만 보내면 재색인 없이 라벨만 변경된다. 모든 필드는 옵셔널.
+ * `name` / `external_id` 만 보내면 재색인 없이 라벨·멱등 키만 변경된다.
+ * 문서 id 는 항상 유지되므로 검색 결과의 `document_id` 참조가 깨지지 않는다.
  */
 interface UpdateDocumentRequest {
     name?: string;
     content?: string;
-    /** base64 인코딩 바이너리 파일 재업로드 (PDF/DOCX/text). source_type 무관하게 추출. */
+    /** 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;
@@ -6977,6 +6986,7 @@ interface DocumentResponse {
     source_type: string;
     mime_type?: string;
     source_url?: string;
+    external_id?: string;
     file_size: number;
     chunk_count: number;
     status: 'pending' | 'processing' | 'ready' | 'failed';
@@ -7035,6 +7045,14 @@ 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;
 }
 
 /**
@@ -7113,9 +7131,60 @@ declare class KnowledgeAPI {
      *     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 파일).
      *
@@ -7160,31 +7229,6 @@ declare class KnowledgeAPI {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<DocumentResponse>;
-    /**
-     * 문서 수정 (재색인)
-     *
-     * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-     * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-     * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-     * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-     *
-     * @param kbID - 지식 베이스 ID
-     * @param docID - 문서 ID
-     * @param data - 수정 요청 (모든 필드 옵셔널)
-     * @returns 수정된 문서 정보
-     *
-     * @example
-     * ```typescript
-     * // 내용 갱신 (전체 재색인 발생)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-     *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-     * })
-     *
-     * // 이름만 변경 (재색인 없음)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-     * ```
-     */
-    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
     /**
      * 문서 목록 조회
      *
@@ -7285,6 +7329,11 @@ interface AISource {
 }
 interface AIChatResponse {
     content: string;
+    /**
+     * 추론 모델(Qwen3 reasoning, OpenAI o-series, DeepSeek-R1 등)의 사고 과정.
+     * 최종 답변(`content`)과 분리되어 제공됩니다. 추론 모델이 아니면 비어 있습니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     usage?: {
         promptTokens: number;
@@ -7296,9 +7345,30 @@ interface AIChatResponse {
     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[];
@@ -7309,6 +7379,7 @@ interface AIStreamChunk {
     result?: string;
     success?: boolean;
     durationMs?: number;
+    searching?: AgenticSearchProgress;
 }
 
 /**
@@ -7352,6 +7423,7 @@ declare class AIAPI {
      *     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)
@@ -7360,8 +7432,19 @@ declare class AIAPI {
      */
     chatStream(request: AIChatRequest, callbacks: {
         onSources?: (sources: AISource[]) => void;
+        /**
+         * 추론 모델의 사고 과정 델타. 추론 모델(Qwen3 reasoning, o-series 등)을
+         * 사용할 때만 호출되며, 최종 답변은 `onToken`으로 별도 전달됩니다.
+         */
+        onReasoning?: (reasoning: string) => void;
         onToken?: (content: string) => void;
         onToolEvent?: (event: AIToolEvent) => void;
+        /**
+         * Agentic 검색(`agentic: true`) 진행 상황. agentic 검색이 검색어를
+         * 생성하고 다중 라운드로 검색하는 각 단계마다 호출되어, "검색 중…"
+         * 진행 UI 를 구성할 수 있다. agentic 미사용 시 호출되지 않는다.
+         */
+        onSearching?: (progress: AgenticSearchProgress) => void;
         onDone?: () => void;
         onError?: (error: string) => void;
     }): Promise<void>;

package/dist/index.d.ts

@@ -6952,24 +6952,33 @@ interface CreateDocumentRequest {
      * 비어있으면 서버가 매직 바이트로 자동 추정 — 정확도를 위해 명시 권장.
      */
     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` 만 보내면 재색인 없이 라벨만 변경된다. 모든 필드는 옵셔널.
+ * `name` / `external_id` 만 보내면 재색인 없이 라벨·멱등 키만 변경된다.
+ * 문서 id 는 항상 유지되므로 검색 결과의 `document_id` 참조가 깨지지 않는다.
  */
 interface UpdateDocumentRequest {
     name?: string;
     content?: string;
-    /** base64 인코딩 바이너리 파일 재업로드 (PDF/DOCX/text). source_type 무관하게 추출. */
+    /** 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;
@@ -6977,6 +6986,7 @@ interface DocumentResponse {
     source_type: string;
     mime_type?: string;
     source_url?: string;
+    external_id?: string;
     file_size: number;
     chunk_count: number;
     status: 'pending' | 'processing' | 'ready' | 'failed';
@@ -7035,6 +7045,14 @@ 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;
 }
 
 /**
@@ -7113,9 +7131,60 @@ declare class KnowledgeAPI {
      *     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 파일).
      *
@@ -7160,31 +7229,6 @@ declare class KnowledgeAPI {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<DocumentResponse>;
-    /**
-     * 문서 수정 (재색인)
-     *
-     * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-     * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-     * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-     * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-     *
-     * @param kbID - 지식 베이스 ID
-     * @param docID - 문서 ID
-     * @param data - 수정 요청 (모든 필드 옵셔널)
-     * @returns 수정된 문서 정보
-     *
-     * @example
-     * ```typescript
-     * // 내용 갱신 (전체 재색인 발생)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-     *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-     * })
-     *
-     * // 이름만 변경 (재색인 없음)
-     * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-     * ```
-     */
-    updateDocument(kbID: string, docID: string, data: UpdateDocumentRequest): Promise<DocumentResponse>;
     /**
      * 문서 목록 조회
      *
@@ -7285,6 +7329,11 @@ interface AISource {
 }
 interface AIChatResponse {
     content: string;
+    /**
+     * 추론 모델(Qwen3 reasoning, OpenAI o-series, DeepSeek-R1 등)의 사고 과정.
+     * 최종 답변(`content`)과 분리되어 제공됩니다. 추론 모델이 아니면 비어 있습니다.
+     */
+    reasoning?: string;
     finishReason?: string;
     usage?: {
         promptTokens: number;
@@ -7296,9 +7345,30 @@ interface AIChatResponse {
     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[];
@@ -7309,6 +7379,7 @@ interface AIStreamChunk {
     result?: string;
     success?: boolean;
     durationMs?: number;
+    searching?: AgenticSearchProgress;
 }
 
 /**
@@ -7352,6 +7423,7 @@ declare class AIAPI {
      *     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)
@@ -7360,8 +7432,19 @@ declare class AIAPI {
      */
     chatStream(request: AIChatRequest, callbacks: {
         onSources?: (sources: AISource[]) => void;
+        /**
+         * 추론 모델의 사고 과정 델타. 추론 모델(Qwen3 reasoning, o-series 등)을
+         * 사용할 때만 호출되며, 최종 답변은 `onToken`으로 별도 전달됩니다.
+         */
+        onReasoning?: (reasoning: string) => void;
         onToken?: (content: string) => void;
         onToolEvent?: (event: AIToolEvent) => void;
+        /**
+         * Agentic 검색(`agentic: true`) 진행 상황. agentic 검색이 검색어를
+         * 생성하고 다중 라운드로 검색하는 각 단계마다 호출되어, "검색 중…"
+         * 진행 UI 를 구성할 수 있다. agentic 미사용 시 호출되지 않는다.
+         */
+        onSearching?: (progress: AgenticSearchProgress) => void;
         onDone?: () => void;
         onError?: (error: string) => void;
     }): Promise<void>;

package/dist/index.js

@@ -8050,6 +8050,15 @@ var KnowledgeAPI = class {
    *     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',
+   * })
    * ```
    */
   async addDocument(kbID, data) {
@@ -8058,6 +8067,58 @@ var KnowledgeAPI = class {
       data
     );
   }
+  /**
+   * 문서 수정 (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' },
+   * })
+   * ```
+   */
+  async updateDocument(kbID, docID, data) {
+    return this.http.put(
+      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
+      data
+    );
+  }
+  /**
+   * 파일로 문서 수정 (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 수정된 문서 정보
+   */
+  async updateDocumentFromFile(kbID, docID, file, options) {
+    const { data, mimeType } = await readFileInput(file);
+    return this.updateDocument(kbID, docID, {
+      name: options?.name,
+      file_content: data,
+      mime_type: mimeType,
+      metadata: options?.metadata
+    });
+  }
   /**
    * 파일을 KB 에 추가 (PDF / DOCX / text 파일).
    *
@@ -8109,36 +8170,6 @@ var KnowledgeAPI = class {
       metadata: options?.metadata
     });
   }
-  /**
-   * 문서 수정 (재색인)
-   *
-   * `content` / `file_content` / `metadata` 중 하나라도 포함하면 전체 재색인이 일어나며
-   * 색인 토큰이 다시 과금됩니다. `name` 만 보내면 재색인 없이 라벨만 변경됩니다.
-   * 재색인 시 서버는 status='pending' 으로 즉시 응답하고 색인은 백그라운드로 진행됩니다
-   * (addDocument 와 동일) — get/listDocuments 로 'ready' 전환을 확인하세요.
-   *
-   * @param kbID - 지식 베이스 ID
-   * @param docID - 문서 ID
-   * @param data - 수정 요청 (모든 필드 옵셔널)
-   * @returns 수정된 문서 정보
-   *
-   * @example
-   * ```typescript
-   * // 내용 갱신 (전체 재색인 발생)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', {
-   *     content: '환불은 구매 후 14일 이내에 가능합니다...'
-   * })
-   *
-   * // 이름만 변경 (재색인 없음)
-   * await cb.knowledge.updateDocument('kb-id', 'doc-id', { name: '환불 정책 v2' })
-   * ```
-   */
-  async updateDocument(kbID, docID, data) {
-    return this.http.put(
-      `/v1/public/knowledge-bases/${kbID}/documents/${docID}`,
-      data
-    );
-  }
   /**
    * 문서 목록 조회
    *
@@ -8232,6 +8263,7 @@ var AIAPI = class {
    *     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)
@@ -8290,9 +8322,14 @@ var AIAPI = class {
             });
             continue;
           }
-          if (event.type === "heartbeat" || event.type === "searching") {
+          if (event.type === "searching") {
+            if (event.searching) callbacks.onSearching?.(event.searching);
+            continue;
+          }
+          if (event.type === "heartbeat") {
             continue;
           }
+          if (event.reasoning) callbacks.onReasoning?.(event.reasoning);
           if (event.content) callbacks.onToken?.(event.content);
           if (event.done) {
             callbacks.onDone?.();